Fix: Simulator Download Stuck in Xcode

Written by

in

Quick answer: If a Simulator runtime download stalls in Xcode, try downloading the iOS platform with xcodebuild -downloadPlatform iOS, or download a compatible runtime image from Apple and import it. For older Xcode versions, you can also try placing the downloaded file in Xcode’s download cache and restarting the installation.

Why this happens

Xcode downloads Simulator runtimes separately from the main Xcode app. A stalled progress bar or timeout can occur while Xcode is fetching the runtime, even when your Mac otherwise has an internet connection. A working network connection alone does not establish why a particular download failed.

The installation method depends on your Xcode version. Recent versions provide command-line options for downloading or importing a platform runtime. The cache workaround described below comes from an older Xcode workflow and may not work in current releases.

How to fix it

1. Try the Xcode command-line download

First, check which Xcode installation your command-line tools are using. This matters if you have more than one copy of Xcode installed.

Open Terminal and run:

xcode-select -p
xcodebuild -version

If these point to an older or unexpected installation, select the intended Xcode app. Adjust the path if your app has a different name or location:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Changing this selection affects other command-line developer tools on the Mac, so switch it back afterward if another project depends on a different Xcode version.

Check whether your Xcode supports platform downloads:

xcodebuild -help

If the help output includes -downloadPlatform, run:

xcodebuild -downloadPlatform iOS

Wait for the command to finish, then reopen Xcode and check whether an iOS Simulator destination is available. This command downloads a platform runtime supported by the selected Xcode; it should not be assumed to fetch a specific older iOS version.

If the command also fails, note its error output. The command-line route may offer a different way to observe the operation, but it does not guarantee a fix for an underlying network or server problem.

2. Download an Apple runtime image and import it

If you need to download the file separately, look for the required Simulator runtime in Apple Developer Downloads. Sign in if prompted, and search for the iOS Simulator runtime version you need. Choose an image compatible with your Xcode version and Mac; an older runtime is not necessarily usable with a newer Xcode or every Mac architecture.

Once the image has downloaded, check xcodebuild -help for -importPlatform. If your selected Xcode supports it, import the downloaded disk image using its actual path:

xcodebuild -importPlatform /path/to/Simulator_Runtime.dmg

Replace the example path with the path to your downloaded file. You can drag the file from Finder into Terminal to insert its path. After the command finishes, open Xcode and check its available Simulator destinations.

Keep the downloaded image until you have confirmed that the runtime is available. If the import reports that the image is invalid or incompatible, verify that the download completed and that you chose the right runtime for your Xcode installation. Download runtime images from Apple rather than an unverified mirror.

3. Try the download-cache workaround on older Xcode

For the older Xcode workflow in the source material, a downloaded Simulator image could be placed in Xcode’s cache. Starting the same download again in Xcode could then make Xcode use the cached file and install it. This is a workaround, not a guaranteed installation method for current Xcode versions.

If you already have the matching image from Apple, skip to the cache step. Otherwise, on an older Xcode version where the download URL appears in Console, try the following:

  1. Open Xcode’s preferences and find the Simulator download under Components or Downloads. The section name varies by Xcode version.
  2. Open the macOS Console app. Start the runtime download in Xcode, then cancel it.
  3. Look in Console for a message associated with the canceled download and its URL. Console output can be noisy, and the URL may not appear in every Xcode version.
  4. If you find a download URL, check that it is an HTTPS URL from Apple before using it. Treat the full URL as potentially sensitive and avoid posting it publicly.
  5. In Terminal, change to a scratch directory and download the file. Replace the example URL with the one you found, keeping the quotes:
cd ~/Downloads
curl -fL -O 'https://example.apple.com/path/to/runtime.dmg'

The URL above is a placeholder, not a download link. -O is an uppercase letter, not zero; it saves the download using the remote filename. -L follows redirects, and -f makes curl report HTTP errors. Check that curl finishes successfully and that the result is the expected disk image, not a sign-in page or other response.

  1. In Finder, choose Go > Go to Folder and enter:
~/Library/Caches/com.apple.dt.Xcode/Downloads
  1. Copy the downloaded image into that folder, keeping its filename unchanged. If the folder does not exist, create the Downloads folder inside com.apple.dt.Xcode if that parent folder is present.
  2. Return to Xcode and start the download for the same runtime again. Check whether Xcode recognizes the cached file and proceeds to install it.

The original workaround also mentioned removing *.dvtdownloadableindex files, but did not establish that this was required. Try the cached image first rather than deleting cache files. If Xcode ignores the image, use the import method above when available; cache layout and behavior can change between releases.

4. Check runtime compatibility before repeating the download

A successfully downloaded image is not the same as an installed, usable Simulator runtime. If Xcode does not offer the expected destination after installation, confirm that the image matches the runtime you requested and is supported by your Xcode and Mac.

The original question involved iOS 7.1 and 8.1 runtimes with Xcode 6.2. Those are historical versions, so do not assume that instructions or runtime files for them apply to a current Xcode installation. If you must use an older environment, check its compatibility before replacing or copying files between Xcode installations.

How to prevent it

  • Check the selected Xcode with xcode-select -p before running command-line installation commands.
  • Keep a verified Apple runtime image until you have confirmed that installation succeeded.
  • Check compatibility before downloading an older runtime for a newer Xcode or a different Mac.
  • Keep download URLs and Console logs private when they may contain sensitive information.

FAQ

Can I download an Xcode Simulator runtime directly?

Yes. Look for the runtime in Apple Developer Downloads, then use xcodebuild -importPlatform if your Xcode version supports that option. The downloaded runtime still needs to be installed or imported before Xcode can use it.

Can I resume a stuck Simulator download by copying it into Xcode’s cache?

The cache method worked for some older Xcode versions: placing the complete matching file in the download cache allowed Xcode to find it when the download was restarted. It is not guaranteed to work with current versions, and a partial or mismatched file may not be usable.

Can I copy an old Simulator runtime into a new Xcode app?

Do not assume that copying a runtime between Xcode installations will make it compatible. Prefer installing a runtime supported by the destination Xcode through its available download or import workflow.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.