How to install old iOS Simulator Runtimes from Command-line

June 30, 2024 1 minute read

Introduction

There came a day when we needed to run Unit or E2E tests on older iOS versions on CI. Sounds like a piece of cake. What could go wrong?

Let’s see what options we have.

xcode-install a.k.a xcversion

⛔️ Deprecated now. But back then it was a no-brainer.

$ gem install xcode-install
$ xcversion simulators --install='iOS 13.7'

###############################           82%
######################################## 100%
Successfully installed iOS 13.7 Simulator

xcodes

Picked up the baton, but… being broken for a few weeks every time Apple updates the API.

$ brew install xcodesorg/made/xcodes || mint install XcodesOrg/xcodes
$ sudo xcodes runtimes install "iOS 14.5"

Downloading Runtime iOS 13.7: 82%
Downloading Runtime iOS 13.7: 100%
Mounting DMG
Expanding pkg
Expanded pkg into /Users/runner/Library/Caches/XcodeInstall/com.apple.pkg.iPhoneSimulatorSDK14_5
Unmounting DMG
Setting package installation location
Rebuilding package
Please authenticate to install iOS 14.5 Simulator...
Successfully installed iOS 14.5 Simulator

Easily handles the runtimes’ download, but when it comes to installation, it’s not all rosy. Let’s use it to download the runtime and combine it with some custom script to install the downloaded image.

$ brew install blacktop/tap/ipsw
$ echo "iOS 15.5 Simulator" | ipsw download xcode --sim

Downloading file=iOS_15.5_Simulator_Runtime.dmg
  4.35 GiB / 5.04 GiB [=============>-----| 33s ] 38.69 MiB/s
  5.04 GiB / 5.04 GiB [===================| ✅  ] 37.54 MiB/s

$ dmg_file=$(ls *.dmg)
$ sh install_runtime.sh "${dmg_file}"

Mounting iOS_15.5_Simulator_Runtime.dmg on /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.NFC0jygSj0...
Checksumming Driver Descriptor Map (DDM : 0)
Checksumming  (Apple_Free : 1)
Checksumming Apple (Apple_partition_map : 2)
Checksumming disk image (Apple_HFS : 3)
Checksumming  (Apple_Free : 4)
Detected packaged runtime.
Found package /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.NFC0jygSj0/iPhoneSimulatorSDK15_5.pkg (sdk iPhoneSimulatorSDK15_5).
Expanding package /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.NFC0jygSj0/iPhoneSimulatorSDK15_5.pkg to /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.Y3CN2N4Wgv/expanded...
Rewriting package install location to /Library/Developer/CoreSimulator/Profiles/Runtimes/iPhoneSimulatorSDK15_5.simruntime...
Re-assembling the package /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.Y3CN2N4Wgv/iPhoneSimulatorSDK15_5.pkg...
Installing /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.Y3CN2N4Wgv/iPhoneSimulatorSDK15_5.pkg...
installer: Package name is iPhoneSimulatorSDK15_5
installer: Upgrading at base path /
installer: The upgrade was successful.
Installed iOS 15.5.
Removing /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.Y3CN2N4Wgv...
Unmounting /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.NFC0jygSj0...
"disk12" ejected.
Removing /var/folders/rl/swm2ljqn187g5y81d6mp8h840000gn/T/tmp.NFC0jygSj0...

Conclusion

Turns out dealing with older runtimes is not that easy and obvious. All above come with pros and cons and decision is yours to take. Here I’ve just shared the options.

By the way, keep in mind that packaged iOS Simulator runtimes (everything below 16) are not supported on hosts after macOS 13.3.99. So juggling the macOS and Xcode versions is also on the table 🤠