Simulator runtimes and CoreSimulator caches: reclaim tens of GB

Part of: Mac disk cleanup for developers: every cache, what it costs to rebuild (Developers)

Simulators can hold tens of gigabytes on a Mac. Two different things take the space: runtimes, which are the simulated operating systems, and devices, which are the simulated phones that run on them. Runtimes are large and cost a download to get back. Devices are small by comparison but hold your test data.

A simulator is a pretend iPhone, iPad or watch that runs on your Mac so you can test apps without a real device. Xcode installs and uses them.

See what you have

Two read-only commands list everything:

xcrun simctl runtime list
xcrun simctl list devices

The first prints installed runtimes and their disk images. The second prints every simulated device, grouped by system version, with its state such as Shutdown. Neither changes anything.

To see sizes:

du -sh ~/Library/Developer/CoreSimulator/Devices /Library/Developer/CoreSimulator

On a recent Xcode, the runtimes are stored as disk images under /Library/Developer/CoreSimulator, outside your home folder. Devices are under ~/Library/Developer/CoreSimulator/Devices. On the Mac used to check this article, the runtime folder was much larger than the devices folder. That is typical, because each runtime is a full operating system.

Runtimes vs devices vs caches

• Runtimes: the simulated system software, for example one iOS version. Several gigabytes each. Xcode downloads them when you add a platform.
• Devices: one entry per simulated model and system version. Each has its own folder with apps and data.
• Caches: a folder at ~/Library/Developer/CoreSimulator/Caches that holds temporary files. It is often small or empty.

Safe, risky, never

• Safe: runtimes for system versions you no longer test on, devices you never open, and the contents of Caches. Cost: a download for a runtime you need later, or a minute to create a device.
• Risky: a device with an app installed and data set up for testing. Removing the device removes both.
• Never: do not delete runtime disk images by hand from /Library/Developer/CoreSimulator. They are managed by the system. Use Xcode’s settings so the system updates its records.

How to reclaim space

1. Run xcrun simctl runtime list and note the runtimes. Decide which system versions you still test on.
2. Quit Xcode and any running simulator.
3. Remove old runtimes from Xcode’s own settings. Let Xcode do this, so the registry of installed runtimes stays correct.
4. Look at the device list. Devices tied to a removed runtime become unavailable. You can list them with xcrun simctl list devices unavailable.
5. Leave the leftover devices alone unless one is large. An empty device is small.

The total saved is mostly from step 3.

What breaks and what it costs

Nothing breaks if you remove a runtime you do not use. A project that targets that system version will ask you to download the runtime again when you run it, and the download is large. Removing a device loses its apps and saved state, so keep the devices where you stored logins or test data.

If you remove a runtime and then run a project that needs it, Xcode will usually prompt you to install it. That is a download, not lost work.

A note on automation

Many online posts use simctl commands that delete devices or erase them in bulk. Those are fast, but they also wipe the data inside your devices and cannot be undone. This article does not give those commands: look at the lists above and remove runtimes through Xcode, which shows you what is going away.

For the rest of the Xcode folders, see Cleaning up Xcode, and whether it is safe to delete ~/Library/Developer. The full list is in the developer cleanup guide.

Worked example: two runtimes, one in use

Say you test on only one iOS version. Run the read-only list:

xcrun simctl list runtimes

On the Mac used to check this article, it printed two iOS runtimes. Each line shows a version and a build number. If your projects target only the newer one, the older one is the candidate. It is a full operating system on disk, so it is a bigger saving than any device.

The steps are short. Note the version you want to remove. Quit Xcode and the simulator. Open Xcode’s settings and remove that runtime there. Run the list command again, and the runtime should be gone.

Check for broken devices

After a runtime is removed, its devices stay in the list but cannot start. See them with:

xcrun simctl list devices unavailable

On that Mac the result had a heading for each iOS version and no devices under them. That is the healthy answer. If you do see devices there, they belong to a runtime that is gone. They take little space, but they clutter the list. Leave them unless you want a tidy list.

If something goes wrong

• A project says the runtime is missing. Xcode needs the version you removed. Install it again in Xcode’s settings. This is a large download.
• The run destination list is shorter than before. That is expected after removing a runtime. Pick a device that matches a runtime you kept.
• Disk space did not change. The runtime disk images live outside your home folder. Run df -h / before and after, because du on your home folder will not show the change.
• A removal seems stuck. Quit Xcode, open it again and retry. Do not delete the image files by hand.

When not to clean

Keep a runtime if you support that system version in a shipping app. You may need it to reproduce a bug a customer reports. Re-downloading is slow, so be sure before you remove the last copy.

Check the size with DiskJoy

DiskJoy is our product. Its scan reads your disk and shows how large the simulator folders are, read-only. Cleanup is not built yet, so DiskJoy does not remove runtimes or devices today. Use the scan to see how large they are, then remove runtimes in Xcode.