xcrun simctl not found? As duas causas e a solução
Você digita xcrun simctl list e recebe um erro em vez dos simuladores. Dois problemas diferentes causam isso, e cada um tem uma solução diferente. O texto do erro mostra qual é o seu.
Topamos com o segundo em um rack inteiro de Mac minis novos. O Xcode estava instalado e o xcodebuild -version funcionava. Mesmo assim, todo build de iOS para o simulador teria falhado. Veja o que cada erro significa e os comandos exatos que resolveram.
Qual é o seu erro?
| Você vê | Significa | Confirme com | Solução |
|---|---|---|---|
| xcrun: unable to find utility "simctl" | O Command Line Tools está selecionado, não o Xcode | xcode-select -p | sudo xcode-select -s /Applications/Xcode.app |
| simctl: No such file or directory | A primeira execução do Xcode nunca rodou | xcodebuild -checkFirstLaunchStatus | sudo xcodebuild -runFirstLaunch |
Causa 1: o Command Line Tools está selecionado
Esta é a mensagem:
xcrun: error: unable to find utility "simctl", not a developer tool or in PATH
O Command Line Tools traz compiladores e git, mas nenhum simulador. Se ele for o diretório de desenvolvedor ativo, o xcrun procura ali e não encontra o simctl. Veja qual está ativo:
xcode-select -p # /Library/Developer/CommandLineTools (the problem) # /Applications/Xcode.app/Contents/Developer (what you want)
Aponte para o Xcode. Use o caminho real se o seu Xcode tiver a versão no nome.
sudo xcode-select -s /Applications/Xcode.app xcrun simctl list runtimes
Causa 2: a primeira execução do Xcode nunca rodou
Este parece mais estranho. O Xcode está selecionado, e o próprio simctl falha:
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 você abre o Xcode pela primeira vez, ele instala alguns pacotes de sistema. Um deles é o CoreSimulator, em /Library/Developer/PrivateFrameworks. O simctl dentro do Xcode é um script pequeno que repassa o trabalho para esse framework. Se o Xcode foi instalado mas nunca aberto, o framework não está lá.
Isso é comum em máquinas de CI e em Macs sem monitor. Ninguém abre o Xcode nelas. Ferramentas que instalam o Xcode para você, como o xcodes, copiam o app mas não rodam a primeira execução. Você pode confirmar:
xcodebuild -checkFirstLaunchStatus; echo $? # 69 means first launch has not run. 0 means it has.
A solução são dois comandos:
# 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
Nos nossos minis M6 com Xcode 26.6, o primeiro comando levou 8 segundos. O segundo baixou o runtime do iOS 26.5 em uns quatro minutos e meio e usou cerca de 9 GB de disco. Não precisou de Apple ID. Depois:
xcrun simctl list runtimes == Runtimes == iOS 26.5 (26.5 - 23F77) - com.apple.CoreSimulator.SimRuntime.iOS-26-5
Faça um Mac de CI verificar a si mesmo
A armadilha é que o xcodebuild -version funciona normalmente em um Mac com esse problema. Uma verificação de saúde baseada nele passa, e o primeiro build para o simulador falha. Verifique o que você realmente precisa:
Agora rodamos essas verificações quando um Mac entra na nossa frota. Cada máquina da MacRun já vem com a primeira execução do Xcode feita e um runtime de simulador iOS instalado, então o primeiro build nela simplesmente funciona.
Perguntas
- Por que o xcrun diz que não encontra o simctl?
- Normalmente porque o diretório de desenvolvedor ativo é o Command Line Tools, não o Xcode. O Command Line Tools não tem as ferramentas de simulador. Aponte o xcode-select para o Xcode com sudo xcode-select -s /Applications/Xcode.app e tente de novo.
- O que significa "simctl: No such file or directory"?
- O Xcode está selecionado, mas os pacotes da primeira execução nunca foram instalados. Esses pacotes colocam o CoreSimulator em /Library/Developer/PrivateFrameworks. Rode sudo xcodebuild -runFirstLaunch para instalar.
- O xcodebuild -downloadPlatform iOS precisa de Apple ID?
- Não. Nos nossos Macs com Xcode 26.6 ele baixou e instalou o runtime do simulador iOS 26.5 sem login. Levou uns quatro minutos e meio e usou cerca de 9 GB de disco.
- Como verifico se um Mac de CI está pronto antes de um build?
- Rode xcodebuild -checkFirstLaunchStatus, que retorna 0 quando a primeira execução já foi feita. Depois rode xcrun simctl list runtimes e procure pelo menos uma linha de iOS.
Faça suas próprias contas na calculadora ou alugue um runner.