xcrun simctl not found? The two causes and the fix
You type xcrun simctl list and get an error instead of simulators. Two different problems cause this, and they need different fixes. The error text tells you which one you have.
We hit the second one across a rack of new Mac minis. Xcode was installed and xcodebuild -version worked. Every iOS simulator build would still have failed. Here is what each error means and the exact commands that fixed it.
Which error do you have?
| You see | It means | Confirm with | Fix |
|---|---|---|---|
| xcrun: unable to find utility "simctl" | The Command Line Tools are selected, not Xcode | xcode-select -p | sudo xcode-select -s /Applications/Xcode.app |
| simctl: No such file or directory | Xcode's first launch never ran | xcodebuild -checkFirstLaunchStatus | sudo xcodebuild -runFirstLaunch |
Cause 1: the Command Line Tools are selected
This is the message:
xcrun: error: unable to find utility "simctl", not a developer tool or in PATH
The Command Line Tools give you compilers and git, but no simulators. If they are the active developer directory, xcrun looks there and finds no simctl. Check which one is active:
xcode-select -p # /Library/Developer/CommandLineTools (the problem) # /Applications/Xcode.app/Contents/Developer (what you want)
Point it at Xcode. Use the real path if your Xcode has a version in its name.
sudo xcode-select -s /Applications/Xcode.app xcrun simctl list runtimes
Cause 2: Xcode's first launch never ran
This one looks stranger. Xcode is selected, and simctl itself fails:
Install Started Install Failed: Authorization is required to install the packages. /Applications/Xcode.app/Contents/Developer/usr/bin/simctl: line 15: /Library/Developer/PrivateFrameworks/CoreSimulator.framework/Versions/A/Resources/bin/simctl: No such file or directory
When you open Xcode for the first time, it installs some system packages. One of them is CoreSimulator, in /Library/Developer/PrivateFrameworks. The simctl in Xcode is a small script that hands off to that framework. If Xcode was installed but never opened, the framework is not there.
This is common on CI machines and headless Macs. Nobody opens Xcode on them. Tools that install Xcode for you, like xcodes, copy the app but do not run its first launch. You can confirm it:
xcodebuild -checkFirstLaunchStatus; echo $? # 69 means first launch has not run. 0 means it has.
The fix is two commands:
# 1. install Xcode's first-launch packages, including CoreSimulator sudo xcodebuild -runFirstLaunch # 2. install an iOS simulator runtime if there is none sudo xcodebuild -downloadPlatform iOS
On our M6 minis with Xcode 26.6, the first command took 8 seconds. The second downloaded the iOS 26.5 runtime in about four and a half minutes and used about 9 GB of disk. It needed no Apple ID. Then:
xcrun simctl list runtimes == Runtimes == iOS 26.5 (26.5 - 23F77) - com.apple.CoreSimulator.SimRuntime.iOS-26-5
Make a CI Mac check itself
The trap is that xcodebuild -version works fine on a Mac with this problem. A health check built on it passes, and the first simulator build fails. Check the thing you actually need instead:
We now run these checks when a Mac joins our fleet. Each MacRun machine comes with Xcode's first launch done and an iOS simulator runtime installed, so the first build on it just works.
Questions
- Why does xcrun say it cannot find simctl?
- Usually because the active developer directory is the Command Line Tools, not Xcode. The Command Line Tools have no simulator tools. Point xcode-select at Xcode with sudo xcode-select -s /Applications/Xcode.app and try again.
- What does "simctl: No such file or directory" mean?
- Xcode is selected, but its first-launch packages were never installed. Those packages put CoreSimulator in /Library/Developer/PrivateFrameworks. Run sudo xcodebuild -runFirstLaunch to install them.
- Does xcodebuild -downloadPlatform iOS need an Apple ID?
- No. On our Macs with Xcode 26.6 it downloaded and installed the iOS 26.5 simulator runtime with no sign-in. It took about four and a half minutes and used about 9 GB of disk.
- How do I check a CI Mac is ready before a build?
- Run xcodebuild -checkFirstLaunchStatus, which returns 0 when first launch is done. Then run xcrun simctl list runtimes and look for at least one iOS line.
Run your own numbers on the calculator or lease a runner.