← blog

xcrun simctl not found? As duas causas e a solução

25 de outubro de 2026 · 5 min de leitura

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?

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.