macOS: xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools)

안녕하세요, BlueByte입니다. macOS 업그레이드 다음 날 아침 git status를 치면 xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun이 나옵니다. 이어서 make, clang, brew install, npm install도 같은 식으로 실패합니다. 저장소는 멀쩡하고, Apple 패키지 하나 말고는 다시 설치할 것이 없습니다. 오늘은 shim이 실제로 무엇을 찾는지, 업그레이드가 왜 그 디렉터리를 비우는지, 어느 경우인지 확인하는 법, 경우별 해결, 그리고 다음 업그레이드를 무탈하게 넘기는 방법까지 하나씩 짚어보겠습니다.

xcrun이 불평하는 것, 그리고 이 오류의 여러 모습

macOS에서 /usr/bin의 개발 명령 — git, clang, make, swift, python3 — 은 래퍼입니다. Apple의 Command Line Tools 문서는 이를 shim이라 부릅니다. 각 shim은 활성 developer 디렉터리를 물어본 뒤 그 안의 진짜 도구를 실행합니다. 그 디렉터리는 독립형 Command Line Tools 패키지가 설치되는 /Library/Developer/CommandLineTools이거나, Xcode가 선택된 경우 /Applications/Xcode.app/Contents/Developer입니다. 이 오류는 xcrun이 지정된 디렉터리 안에 xcrun이 없다고 말하는 것입니다:

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

선택된 경로가 Xcode인데 Xcode가 사라졌을 때는 형제 메시지가 나옵니다:

xcrun: error: active developer path ("/Applications/Xcode.app/Contents/Developer") does not exist
Use `sudo xcode-select --switch path/to/Xcode.app` to specify the Xcode that you wish to use for command line developer tools, or use `xcode-select --install` to install the standalone command line developer tools.

둘 다 같은 뜻입니다. 포인터는 설정돼 있는데 대상이 비어 있거나 없습니다.

macOS 업그레이드가 디렉터리를 비우는 이유, 그리고 다른 원인들

macOS 메이저 업그레이드. 가장 흔한 경우입니다. Apple 자체 안내도 macOS 업그레이드 후 새 Command Line Tools 릴리스를 확인하라고 합니다. 설치돼 있던 패키지가 새 macOS와 호환되지 않을 수 있기 때문입니다. 실제로는 업그레이드가 /Library/Developer/CommandLineTools는 남기고 usr/bin만 없앤 상태가 되어, xcode-select -p는 여전히 경로를 찍는데 모든 shim이 실패합니다.

Xcode가 삭제되거나 옮겨졌다. xcode-select가 /Applications/Xcode.app을 가리키는 상태에서 Xcode를 휴지통에 넣거나 Xcode-15.app으로 이름을 바꾸거나 디스크를 비우려고 지웠다면 포인터가 허공을 가리킵니다. 위의 두 번째 메시지가 나옵니다.

포인터를 손으로 바꿨다. developer 디렉터리가 아닌 경로로 sudo xcode-select -s를 했거나, dotfile이나 CI 작업에서 export한 DEVELOPER_DIR 환경 변수가 그 셸에서 시스템 설정을 덮어쓴 경우입니다.

설치가 끝나지 않았다. Command Line Tools 대화 상자를 취소했거나 다운로드가 실패해 디렉터리가 부분적으로만 남은 경우입니다. 패키지 영수증이 알려줍니다.

무엇을 설치하기 전에 경로부터 확인하기

명령 세 개면 원인이 갈리고, 어느 것도 시스템을 바꾸지 않습니다:

xcode-select -p
ls /Library/Developer/CommandLineTools/usr/bin/xcrun
pkgutil --pkg-info=com.apple.pkg.CLTools_Executables
echo "DEVELOPER_DIR=${DEVELOPER_DIR:-unset}"

/Library/Developer/CommandLineTools
ls: /Library/Developer/CommandLineTools/usr/bin/xcrun: No such file or directory
No receipt for 'com.apple.pkg.CLTools_Executables' found at '/'.
DEVELOPER_DIR=unset

포인터는 있고 바이너리는 없고 영수증도 없다면 — 패키지가 사라진 것이고 첫 번째 원인입니다. version: 줄이 있는 영수증은 있는데 바이너리가 없다면 깨진 디렉터리이고, 같은 방법으로 고칩니다. ls /Applications에서 찾을 수 없는 Xcode.app을 가리키고 있다면 두 번째 원인입니다. DEVELOPER_DIR이 unset이 아니라면 세 번째 원인이고, 그 셸에서는 이 변수가 xcode-select보다 우선합니다.

해결 1: Command Line Tools를 다시 설치하기

macOS에 패키지를 받아 달라고 요청합니다. Apple이 이 명령과 출력되는 note를 문서화해 두었습니다. 시스템 대화 상자가 뜨면 Install을 누르고 라이선스에 동의합니다:

xcode-select --install

xcode-select: note: install requested for command line developer tools

다운로드는 큽니다 — 패키지에 macOS SDK 전체가 들어 있습니다 — 그리고 관리자 계정이 필요합니다. 바이너리가 여전히 없는데도 명령이 대신 도구가 이미 설치돼 있다며 Software Update로 안내한다고 해서(문구는 macOS 버전마다 다릅니다) 겁먹지 않아도 됩니다. 그것이 깨진 디렉터리 경우입니다. Apple의 제거 절차가 지목하는 디렉터리를 지우고 다시 설치를 요청하세요:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

그 디렉터리에 여러분의 것은 없습니다. Apple의 툴체인과 SDK만 들어 있고 패키지가 다시 만들어 줍니다. 시스템 설정의 Software Update나 softwareupdate --list가 현재 macOS용 Command Line Tools 릴리스를 제안할 수도 있는데, 거기서 설치해도 같은 패키지입니다.

해결 2: 실제로 있는 Xcode를 xcode-select로 가리키기

Xcode가 설치돼 있다면 독립형 패키지는 아예 필요 없습니다 — Xcode에 같은 도구가 들어 있다고 Apple 문서가 분명히 밝힙니다. Xcode를 선택하거나 기본 탐색으로 리셋하세요:

sudo xcode-select -s /Applications/Xcode.app
xcode-select -p

/Applications/Xcode.app/Contents/Developer

sudo xcode-select --reset은 손으로 설정한 경로를 지우고 shim이 존재하는 developer 디렉터리를 찾게 합니다. 두 명령 모두 Mac의 모든 사용자에게 적용되는 설정을 바꾸기 때문에 sudo가 필요합니다.

해결 3: 환경 변수가 시스템 경로를 덮어쓰는 경우

DEVELOPER_DIR은 그것이 설정된 셸에서 xcode-select보다 우선합니다. 어디서 오는지 찾아 지우거나, 실제 디렉터리를 가리키게 하세요:

grep -n DEVELOPER_DIR ~/.zprofile ~/.zshrc ~/.bash_profile 2>/dev/null
unset DEVELOPER_DIR
xcrun --find clang

CI에서는 오히려 이것이 올바른 도구입니다. 공유 러너에서 xcode-select -s를 실행하는 대신 작업 안에서 DEVELOPER_DIR=/Applications/Xcode-16.app을 export하세요.

실제 사례: 밤사이 업그레이드 뒤 죽어 버린 git

한 개발자가 macOS 메이저 업그레이드를 밤새 돌려 두었습니다. 아침에 git pull이 invalid active developer path 메시지로 실패했고, git이 필요한 brew upgrade도 함께 실패했습니다. xcode-select -p는 여전히 /Library/Developer/CommandLineTools를 찍었고, pkgutil --pkg-info는 영수증이 없다고 했습니다. xcode-select --install을 실행해 대화 상자에서 Install을 누르고 다운로드를 기다리자 git --version이 새 패키지의 Apple Git 빌드로 다시 답했습니다. Homebrew는 git을 기다리고 있었을 뿐이라 아무것도 바꾸지 않았는데도 brew doctor가 깨끗했습니다.

고친 뒤 끝까지 확인하고 재발 막기

shim으로 먼저, 그 다음 shim을 거치는 도구로 검증하세요:

xcode-select -p
xcrun --find clang
git --version
pkgutil --pkg-info=com.apple.pkg.CLTools_Executables

/Library/Developer/CommandLineTools
/Library/Developer/CommandLineTools/usr/bin/clang
git version 2.x.y (Apple Git-nnn)
package-id: com.apple.pkg.CLTools_Executables
version: 26.x.0.0.1.…

정확한 버전은 Apple이 해당 macOS용으로 배포하는 패키지에 따라 다릅니다. 다음 업그레이드에 앞서 두려면: macOS 메이저 업데이트 직후, 첫 회의 전에 xcode-select -p와 git --version을 실행하세요. Software Update를 켜 두어 새 Command Line Tools 릴리스가 업데이트로 나타나게 하세요. Xcode에 의존한다면 명시적으로 선택해 두어 오래된 독립형 패키지가 활성 경로가 될 수 없게 하세요.

"tool 'xcodebuild' requires Xcode", 라이선스 프롬프트와는 어떻게 다른가

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance는 도구가 없는 문제가 아닙니다. Command Line Tools는 설치돼 있고 동작하지만, xcodebuild와 xctrace는 Xcode에만 들어 있습니다. Xcode를 설치하고 해결 2로 선택하세요. 그리고 You have not agreed to the Xcode license agreements는 전부 설치돼 있고 shim도 찾았다는 뜻이니 sudo xcodebuild -license를 한 번 실행하면 됩니다.

다음에 이 오류를 만나면 이 순서를 거꾸로 따라가 보세요. xcode-select -p, 그 경로 아래 usr/bin/xcrun에 ls, 영수증을 보는 pkgutil — 나머지는 xcode-select --install에 맡기면 됩니다.