xcrun simctl upgradeでiOSシミュレータデバイスのランタイムを変更する

xcrun simctl upgradeは、既存のシミュレータデバイスのランタイムを、同じUUID・データを保持したまま新しいバージョンに変更するサブコマンドである。

基本的な使い方

upgrade <device> <runtime id>の形式で実行する。

$ xcrun simctl upgrade "TIL Upgrade Test" "com.apple.CoreSimulator.SimRuntime.iOS-18-3"

参考: xcrun simctl cloneでiOSシミュレータデバイスを複製する

cloneは複製先に新しいUUIDを割り当てるのに対し、upgradeは同じUUIDのまま中身のランタイムだけを変更する。デバイスのデータディレクトリ（~/Library/Developer/CoreSimulator/Devices/<UDID>/data）に直接置いたファイルも、upgrade後にそのまま残ることを確認できる。

$ echo "marker" > ~/Library/Developer/CoreSimulator/Devices/<UUID>/data/til-upgrade-marker.txt
$ xcrun simctl upgrade "TIL Upgrade Test" "com.apple.CoreSimulator.SimRuntime.iOS-18-3"
$ ls ~/Library/Developer/CoreSimulator/Devices/<UUID>/data/til-upgrade-marker.txt
/Users/xxx/Library/Developer/CoreSimulator/Devices/<UUID>/data/til-upgrade-marker.txt

古いランタイムへの変更（降格）はできない

コマンド名の通り、upgradeは新しいランタイムへの変更のみ受け付ける。既にiOS 18.3で動いているデバイスを、それより古いiOS 17.5に変更しようとするとエラーになる。

$ xcrun simctl upgrade "TIL Upgrade Test" "com.apple.CoreSimulator.SimRuntime.iOS-17-5"
An error was encountered processing the command (domain=com.apple.CoreSimulator.SimError, code=401):
Invalid runtime

一方、現在と同じランタイムを指定した場合はエラーにならない（実質的に何も変更されない）。

起動中のデバイスは変更できない

参考: xcrun simctl eraseでiOSシミュレータデバイスの内容を初期化する

eraseやcloneと同様、upgradeも起動中（Booted）のデバイスに対して実行すると明確なエラーになる。

$ xcrun simctl boot "TIL Upgrade Test"
$ xcrun simctl upgrade "TIL Upgrade Test" "com.apple.CoreSimulator.SimRuntime.iOS-26-5"
An error was encountered processing the command (domain=com.apple.CoreSimulator.SimError, code=405):
Unable to upgrade device in current state: Booted

変更する前に、デバイスをshutdownしておく必要がある。

存在しないランタイムを指定するとエラーになる

存在しないランタイム識別子を指定すると、Invalid runtimeエラーになる。

$ xcrun simctl upgrade "TIL Upgrade Test" "com.apple.CoreSimulator.SimRuntime.iOS-99-0"
Invalid runtime: com.apple.CoreSimulator.SimRuntime.iOS-99-0

利用可能なランタイムの識別子はsimctl list runtimesで確認できる。