기술 · 실용 가이드

node-gyp가 Python을 못 찾나요? 재설치 전에 경로부터 증명하세요

실제 npm 자식 프로세스, node-gyp 복사본, Python 선택기와 호환성 조건을 확인한 뒤 환경을 바꾸세요.

작성 Watch at Ease News · 4 분 읽기발행 2026. 10. 17. 오전 2:15 UTC

터미널에서 Python이 실행되는 것과 node-gyp가 같은 Python을 사용할 수 있는 것은 다른 주장입니다. 실제 npm 자식 프로세스와 선택 경로를 먼저 증명해야 합니다.

인터프리터 탐지, 버전 승인, 네이티브 도구 체인의 순서로 첫 실패 단계를 따라가면 변경을 작고 되돌릴 수 있게 유지할 수 있습니다.

첫 실패와 설치 환경을 고정합니다

첫 gyp ERR! find Python부터 마지막 명령까지 작업 디렉터리와 Node, npm, node-gyp 버전을 저장하세요. npm install, npm ci, 설치 스크립트, 컨테이너, CI 중 어디서 실패했는지도 기록합니다.

로그의 명령 경로도 보존하세요. 대화형 셸에서 python3가 실행된다는 사실은 npm 자식 프로세스가 같은 PATH, 사용자, 환경, node-gyp를 쓴다는 증거가 아닙니다.

실패 환경에서 node -p "process.execPath", 각 버전, gyp info의 node-gyp 경로를 기록하고 npm config get node_gyp와 설치 스크립트를 확인합니다.

전역 node-gyp 설치가 npm이 쓰는 복사본을 바꿨다고 가정하지 마세요. npm 내부 복사본, 프로젝트 의존성, 패키지 관리자 심이 있을 수 있으므로 실제 로그를 기준으로 합니다.

같은 터미널, 컨테이너 계층, 서비스 계정, CI 단계에서 Python 절대 경로와 sys.executable, sys.version을 확인하고 npm_config_python, PYTHON, NODE_GYP_FORCE_PYTHON과 비교합니다.

공식 선택기는 --python, npm_config_python, PYTHON, NODE_GYP_FORCE_PYTHON입니다. 강제 값이 호환되지 않으면 추가 탐색이 멈춥니다. Windows는 py --list-paths를 사용합니다.

Python 실행 파일이 있어도 버전 때문에 거부될 수 있습니다. 공식 문서는 Python 3.12 이상에 node-gyp 10 이상이 필요하다고 명시합니다. 실패 로그의 버전과 비교하세요.

오래되거나 지원되지 않는 Python이 먼저 선택되면 낡은 값을 제거하거나 호환되는 절대 경로를 지정합니다. 실제 복사본이 바뀐다고 확인한 뒤 업그레이드하고, 오래된 답변만 보고 Python 2를 설치하지 마세요.

Python 선택이 성공하면 상세 로그로 한 번만 다시 실행합니다. 첫 오류가 make, MSBuild, 컴파일러, 헤더, binding.gyp, 네이티브 소스로 이동했다면 탐지 문제는 해결된 것입니다.

Unix에는 make와 C/C++ 컴파일러, Windows에는 Visual C++ 환경이 별도로 필요합니다. Electron 같은 런타임은 자체 헤더가 필요할 수 있습니다.

직접 node-gyp를 실행하면 --python, npm을 통해 실행하면 해당 단계의 npm_config_python을 사용합니다. 넓은 계약이 필요할 때만 PYTHON을 쓰고 강제 값은 호환성 확인 후 사용합니다.

프로젝트, 사용자, 전역, CI의 오래된 값을 먼저 제거하세요. npm_config_와 각 npmrc의 범위를 기록하고 단일 작업 때문에 전체 시스템을 바꾸지 않습니다.

같은 환경에서 원래 npm 명령을 다시 실행하고 의도한 Python 경로와 호환 node-gyp 버전을 확인한 뒤 모듈 로드나 테스트까지 검증합니다. configure 성공만으로는 부족합니다.

이전 값과 새 값, 경로, 버전, 범위, 제거 명령을 기록합니다. 다른 프로젝트에 영향을 주지 않아야 한다면 임시 변수를 해제합니다.