何が起きているのか
xcodebuildを実行したとき、またはCocoaPods、Fastlane、Flutter、React NativeビルドなどこれをラップするツールからBuildされたとき、以下のエラーが発生しました：
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance
簡単に言うと：xcode-selectがフルXcodeアプリを指すべきところを、Command Line Toolsを指しています。CLTは約700 MBの軽量パッケージです。xcodebuildは含まれていません。Xcodeに含まれています。
問題の診断
現在アクティブ開発者ディレクトリがどこを指しているか確認します：
xcode-select -p
出力が/Library/Developer/CommandLineToolsの場合、それが問題です。Xcodeバンドル内を指すべきです。通常は/Applications/Xcode.app/Contents/Developerです。
次に、Xcodeが実際にマシンに存在するか確認します：
ls /Applications/Xcode.app
ディレクトリが存在しない場合はまずXcodeをインストールしてください。ディレクトリが存在する場合は、xcode-selectがそれを使用するよう設定するだけです。
修正方法
オプション1：Xcodeがすでにインストールされている場合（最も一般的なケース）
コマンド1つで解決します：
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
次に、Xcodeライセンス契約に同意します。この手順を省略すると一部のツールが静かに失敗することがあります。2秒で完了し、後の多くのデバッグ時間を節約できます：
sudo xcodebuild -license accept
以上です。以下の「修正の確認」に進んでください。
オプション2：Xcodeがインストールされていない場合
Mac App StoreからXcodeをインストールします。接続速度によっては20〜40分かかります。ダウンロードサイズは10〜15 GBです。チームの環境に合わせた特定バージョンが必要な場合は、Appleのデベロッパーポータルから直接入手してください。
インストールが完了したら：
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
オプション3：Xcodeが標準以外のパスにインストールされている場合
アプリをリネームした場合や、安定版とベータ版を並行使用している場合はパスが異なります。インストール済みのものを確認します：
# インストール済みのXcodeを一覧表示する
ls /Applications/ | grep -i xcode
# 正しいパスを明示的に指定する
sudo xcode-select -s /Applications/Xcode_16.app/Contents/Developer
修正の確認
以下の2つを実行します：
# Xcodeアプリのパスが表示されるはず
xcode-select -p
# 期待される出力: /Applications/Xcode.app/Contents/Developer
# Xcodeのバージョンが正常に表示されるはず
xcodebuild -version
# 期待される出力:
# Xcode 16.x
# Build version 16Cxxx
元のエラーがCocoaPods、Fastlane、Flutterから発生した場合は、そのツールを再実行してください。xcode-selectエラーは解消されているはずです。
なぜ繰り返し起きるのか
インストール順序が通常の原因です。Homebrew、git、その他いくつかのツールは、新しいMacでCommand Line Toolsのインストールを促します。そのためCLTが先にインストールされます。後でフルXcodeアプリをインストールしても、macOSは自動的にxcode-selectのポインタを更新しません。古いCLTパスは手動で変更するまでそのままです。
もう一つのよくあるトリガーはmacOSのメジャーアップグレードです。Sonoma、Sequoiaなど、いくつかのバージョンでは、アップグレード前に正しく設定されていても開発者ディレクトリをCLTにリセットすることがあります。
学んだこと
- Xcodeをインストールまたは更新するたびに、直後に
sudo xcode-select -s /Applications/Xcode.app/Contents/Developerを実行してください。5秒で完了し、このデバッグ全体を省けます。 - macOSのメジャーアップグレード後は、iOSまたはmacOSのビルドに触れる前に
xcode-select -pを確認してください。 - 「requires Xcode」に類したビルドエラーが発生した場合は、まず
xcode-select -pを確認してください。9割の確率でCLTを指しています。 - Flutter、React Native CLI、Fastlane、CocoaPodsはすべて内部で
xcodebuildを呼び出します。ツールが違っても、エラーは同じ、修正方法も同じです。