Node.js: node-sass/node-gyp 빌드 시 ‘Python not found’ 오류 해결하기

1. 문제 정의

Jenkins CI 환경에서 Node.js 프로젝트를 빌드할 때 갑자기 빌드가 실패하는 경우가 있습니다. 로컬 머신에서는 정상 동작하지만, 빌드 서버에서만 반복되는 다음과 같은 에러를 만나게 됩니다.

1
2
3
4
5
6

gyp verb check python checking for Python executable "python2" in the PATH
gyp verb `which` failed Error: not found: python2
gyp verb `which` failed at getNotFoundError (...\node_modules\which\which.js:13:12)
gyp verb `which` failed at F (...\node_modules\which\which.js:68:19)
gyp verb `which` failed at E (...\node_modules\which\which.js:80:29)
gyp verb `which` failed at C:\...\node_modules\which\which.js:89:16

이 문제는 StackOverflow에 475점으로 채택된 아주 흔한 빌드 오류입니다.

2. 원인 탐구

이 에러의 근본 원인을 이해하려면 의존성 체인을 봐야 합니다.

  • node-sass는 sass 컴파일러인 LibSass를 바이너리로 사용합니다.
  • 특정 버전(여기서는 node-sass v3.8.0)은 내부적으로 node-gyp v3.5.0을 사용해 네이티브 모듈을 빌드합니다.
  • node-gyp는 소스에서 네이티브 모듈을 컴파일할 때 빌드 도구(Python, C++ 컴파일러, MSBuild 등)를 요구합니다.

문헌에서 node-gyp의 전제 조건(prerequisite)은 Python이 설치되어 있어야 한다는 것이 명시적으로 확인됩니다. 문제의 사용자는 Jenkins 서버에 Python이 없어 PATH에서 python2를 찾지 못해 which 명령이 실패한 것입니다.

3. 근본 원인 분석

핵심 원인은 **’node-gyp가 빌드 시 요구하는 Python 의존성의 부재’**입니다.

  • 원 질문의 로그에는 checking for Python executable "python2" in the PATH가 실패하는 것이 명확히 보입니다.
  • node-sass는 인기 있는 순수 자바스크립트 모듈이지만, 설치 시 플랫폼용 사전 빌드(prebuilt) 바이너리를 자동 다운로드하려고 합니다. 그것이 실패하면 소스로 빌드하게 되고, 그 시점에 Python이 필요한 겁니다.
  • 따라서 이 오류가 떴다는 것은 “설치 서버가 사전 빌드 바이너리를 받지 못했고, 네이티브 빌드에 필요한 Python/빌드 체인도 없다"는 두 가지가 겹쳐 발생합니다. 로컬에 Python이 있다면 정상이라는 점이 해결 방향을 가리킵니다.

4. 코드 해결책

옵션 A — node-sass를 호환 버전으로 업데이트

StackOverflow 채택 답변에서는 다음을 권장합니다.

1
2

# 현재 node-sass v3.8.0 → 호환되는 최신 버전으로
npm install node-sass@4.5.3 --save-dev
  • node-sass 3.8.0은 Node 5를 지원합니다. Node 5는 이미 수명이 끝났으므로 버전을 맞추며, 만약 Node 8로 올리고 싶다면 에서 node-sass@4.5.3이 필요합니다.

옵션 B — Node.js를 업그레이드

1
2
3

# 이미 Node 6 이상을 쓴다면 node-sass 최신 버전과 호환
nvm install 6
nvm use 6

Node 6 이상에서 최신 node-sass가 더 이상 레거시 node-gyp를 사용하지 않아 Python 2 의존성을 덜 요구합니다.

옵션 C — 빌드 환경에 Python 준비

Jenkins(빌드 서버)에 아래와 같은 전제를 갖춥니다.

  • Python 2 설치 (node-gyp v3.5 요구)
  • 윈도우라면 Visual Studio(C++ 빌드 도구) 또는 MSBuild 필요
  • 이후 npm rebuild node-sass로 네이티브 모듈 재빌드
1
2
3

# (예시, 빌드 서버에서)
npm install
npm rebuild node-sass

5. 향후 예방 조치

  • 레거시 node-sass 대신 최신 빌드 체인으로 마이그레이션하면 더욱 안정적입니다. 현대 프로젝트에서는 sass(Dart Sass) 호환 래퍼로 전환하거나 CI 이미지에 Python 빌드 체인을 사전에 포함합니다.
  • 빌드 서버 Docker 이미지에 python2, 빌드 도구를 미리 넣고 CI 파일에 명시적으로 설치하십시오.
  • npm ci(잠금 파일 기반)를 쓰면 설치 중 바이너리 재다운로드 오류를 초기 발견할 수 있습니다.

출처: StackOverflow — Node.js: Python not found exception due to node-sass and node-gyp