수정 명령 cl.exe 실패: Windows에 해당 파일 또는 디렉터리 없음

Windows에서 pip가 error: command 'cl.exe' failed: no such file or directory를 보고한다면, 대개 패키지를 소스 코드에서 빌드하는 중이며 빌드 프로세스가 Microsoft C/C++ 컴파일러를 찾지 못한 것입니다. C++ 도구가 설치되어 있지 않다면 설치한 다음, 해당 세션에 컴파일러 환경을 설정하는 Visual Studio 개발자 명령 프롬프트에서 pip를 실행하세요. 일부 패키지는 사용 중인 Python 버전에 맞는 미리 빌드된 휠을 제공하므로 로컬 컴파일러 없이 설치할 수도 있습니다.

pip에서 cl.exe가 없다고 보고하는 이유

호환되는 패키지가 미리 빌드되어 있으면 pip는 휠을 설치합니다. 그렇지 않으면 패키지를 소스 코드에서 빌드할 수 있습니다. 일부 Python 바인딩을 포함해 네이티브 구성 요소가 있는 패키지는 빌드 과정에서 C 또는 C++ 컴파일러가 필요합니다. Windows에서 Microsoft Visual C++가 사용하는 컴파일러 실행 파일은 cl.exe입니다.

이 메시지는 빌드 명령이 cl.exe를 실행하려 했지만 현재 환경에서 찾지 못했다는 뜻입니다. 컴파일러 구성 요소가 설치되지 않았거나 현재 터미널이 컴파일러를 찾도록 설정되지 않은 경우에 발생할 수 있습니다. 이 메시지만으로 Python이나 pip가 고장 났다고 단정할 수는 없습니다. 또한 컴파일러를 설치해도 지원되지 않는 패키지 버전이나 누락된 종속성처럼 관련 없는 오류까지 해결되지는 않습니다.

Microsoft C++ 빌드 도구 설치

Visual Studio가 이미 설치되어 있다면 Visual Studio Installer를 열고 해당 설치에서 수정을 선택한 다음 C++를 사용한 데스크톱 개발 워크로드를 선택하세요. C++ 빌드 도구가 포함되어 있는지 확인하고 변경 사항을 적용합니다. 이 워크로드에는 네이티브 패키지 빌드에 쓰이는 컴파일러와 관련 도구가 포함됩니다.

Visual Studio IDE 전체가 필요하지 않다면 Microsoft의 Build Tools 다운로드 페이지에서 Visual Studio Build Tools를 설치하세요. 설치 프로그램에서 C++ 빌드 도구 워크로드와 대상 아키텍처에 필요한 구성 요소를 선택합니다. 버전에 따라 설치 프로그램의 항목 이름이 다를 수 있으므로 설치를 마치기 전에 MSVC 컴파일러 도구가 선택되어 있는지 확인하세요.

워크로드를 설치하면 컴퓨터에서 컴파일러를 사용할 수 있게 되지만, 일반 터미널에는 컴파일러를 찾기 위한 환경 설정이 되어 있지 않을 수 있습니다. 버전에 따라 달라지는 컴파일러 디렉터리를 시스템 PATH에 복사하지 말고, 다음 단계에서 개발자 명령 프롬프트를 사용하세요.

설정된 개발자 환경에서 pip 실행

시작 메뉴에서 C++ 도구와 함께 설치된 Visual Studio Developer Command Prompt 또는 Native Tools Command Prompt를 여세요. 64비트 Python을 사용한다면 x64 프롬프트를 선택하고, 32비트라면 이에 맞는 x86 프롬프트를 선택합니다. 이 프롬프트는 컴파일러를 찾는 데 필요한 경로를 비롯해 해당 터미널 세션의 환경 변수를 설정합니다. 이미 열려 있는 모든 명령 프롬프트나 PowerShell 창의 설정을 바꾸지는 않습니다.

필요하다면 해당 프롬프트에서 프로젝트 디렉터리로 이동한 뒤, 오류가 발생한 것과 동일한 pip install package-name 명령을 실행하세요. 설치하려는 패키지를 사용할 Python 환경에서 명령을 실행해야 합니다. 예를 들어 평소 가상 환경을 사용한다면, 설정된 프롬프트에서 pip를 실행하기 전에 가상 환경을 활성화하세요. 이후 일반 터미널을 새로 열면 개발자 프롬프트의 설정이 이어지지 않습니다.

컴파일러 확인 및 남은 빌드 오류 진단

설치를 다시 시도하기 전에 선택한 프롬프트에서 where cl을 실행해 컴파일러를 찾을 수 있는지 확인하세요. Windows가 cl.exe의 경로를 표시해야 합니다. 파일을 찾을 수 없다는 결과가 나오면 C++ 워크로드 설치가 완료되었는지 확인하고, Python에 맞는 개발자 프롬프트를 다시 여세요. 프롬프트의 아키텍처가 사용 중인 Python 인터프리터와 일치하는지도 확인하세요. 추측한 컴파일러 경로를 직접 추가하지 마세요.

where cl로 컴파일러가 확인되는데도 pip가 같은 명령 누락 메시지를 계속 표시한다면, 설치가 바로 그 프롬프트에서 실행되는지와 의도한 Python 환경이 활성화되어 있는지 확인하세요. 그런 다음 전체 빌드 로그를 살펴보세요. 패키지가 별도의 빌드 도구를 호출하거나 추가 구성 요소가 필요한 컴파일러 설정을 사용할 수 있습니다.

오류가 C++ 진단 메시지, 누락된 헤더 또는 패키지별 빌드 오류로 바뀌었다면 컴파일러 검색은 정상적으로 작동하고 있으며 남은 문제는 빌드의 후속 단계에 있습니다. 전체 출력에서 처음 나오는 핵심 오류를 읽은 다음 패키지의 설치 안내와 사용 중인 Python 버전 및 플랫폼에 호환되는 휠을 제공하는지 확인하세요. cl.exe가 있다는 사실만으로 모든 소스 패키지를 성공적으로 빌드할 수 있는 것은 아닙니다.