← blog

xcrun simctl not found? Le due cause e la soluzione

25 ottobre 2026 · 5 min di lettura

Scrivi xcrun simctl list e invece dei simulatori ottieni un errore. Le cause sono due, e richiedono soluzioni diverse. Il testo dell’errore ti dice quale delle due hai.

Noi abbiamo incontrato la seconda su un intero rack di Mac mini nuovi. Xcode era installato e xcodebuild -version funzionava. Eppure ogni build per il simulatore iOS sarebbe fallita. Ecco cosa significa ogni errore e i comandi esatti che l’hanno risolto.

Quale errore hai?

Causa 1: sono selezionati i Command Line Tools

Questo è il messaggio:

xcrun: error: unable to find utility "simctl", not a developer tool or in PATH

I Command Line Tools ti danno i compilatori e git, ma nessun simulatore. Se sono la developer directory attiva, xcrun cerca lì e non trova simctl. Controlla quale è attiva:

xcode-select -p
# /Library/Developer/CommandLineTools          (the problem)
# /Applications/Xcode.app/Contents/Developer   (what you want)

Puntala su Xcode. Usa il percorso reale se il tuo Xcode ha la versione nel nome.

sudo xcode-select -s /Applications/Xcode.app
xcrun simctl list runtimes

Causa 2: il primo avvio di Xcode non è mai stato eseguito

Questo sembra più strano. Xcode è selezionato, ed è simctl stesso a fallire:

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

Quando apri Xcode per la prima volta, installa alcuni pacchetti di sistema. Uno è CoreSimulator, in /Library/Developer/PrivateFrameworks. Il simctl dentro Xcode è un piccolo script che passa la mano a quel framework. Se Xcode è stato installato ma mai aperto, il framework non c’è.

Succede spesso su macchine di CI e Mac headless. Nessuno ci apre Xcode. Gli strumenti che installano Xcode al posto tuo, come xcodes, copiano l’app ma non eseguono il primo avvio. Puoi verificarlo:

xcodebuild -checkFirstLaunchStatus; echo $?
# 69 means first launch has not run. 0 means it has.

La soluzione sono due comandi:

# 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

Sui nostri mini M6 con Xcode 26.6, il primo comando ha impiegato 8 secondi. Il secondo ha scaricato il runtime iOS 26.5 in circa quattro minuti e mezzo e ha occupato circa 9 GB di disco. Non ha richiesto alcun Apple ID. Poi:

xcrun simctl list runtimes
== Runtimes ==
iOS 26.5 (26.5 - 23F77) - com.apple.CoreSimulator.SimRuntime.iOS-26-5

Fai in modo che un Mac di CI si controlli da solo

La trappola è che xcodebuild -version funziona bene su un Mac con questo problema. Un health check basato su quel comando passa, e la prima build per il simulatore fallisce. Controlla invece ciò che ti serve davvero:

Ora eseguiamo questi controlli quando un Mac entra nella nostra flotta. Ogni macchina MacRun arriva con il primo avvio di Xcode già fatto e un runtime del simulatore iOS installato. Così la prima build funziona e basta.

Domande

Perché xcrun dice che non trova simctl?
Di solito perché la developer directory attiva sono i Command Line Tools, non Xcode. I Command Line Tools non hanno gli strumenti del simulatore. Punta xcode-select su Xcode con sudo xcode-select -s /Applications/Xcode.app e riprova.
Cosa significa "simctl: No such file or directory"?
Xcode è selezionato, ma i suoi pacchetti di primo avvio non sono mai stati installati. Sono loro a mettere CoreSimulator in /Library/Developer/PrivateFrameworks. Esegui sudo xcodebuild -runFirstLaunch per installarli.
xcodebuild -downloadPlatform iOS richiede un Apple ID?
No. Sui nostri Mac con Xcode 26.6 ha scaricato e installato il runtime del simulatore iOS 26.5 senza alcun login. Ci sono voluti circa quattro minuti e mezzo e circa 9 GB di disco.
Come verifico che un Mac di CI sia pronto prima di una build?
Esegui xcodebuild -checkFirstLaunchStatus, che restituisce 0 quando il primo avvio è fatto. Poi esegui xcrun simctl list runtimes e cerca almeno una riga iOS.

Fai i tuoi conti con il calcolatore oppure noleggia un runner.