pip --only-binary=:all:로 “소스 빌드 지옥” 탈출하기

회사/서버 환경에서 pip install 하다가 갑자기 CMake, gcc, ArrowConfig… 같은 에러로 폭발한 적 있죠?
원인 대부분은 휠(wheel)이 없어서 소스 빌드로 빠졌기 때문입니다. 이 글은 그런 상황을 한 줄 옵션으로 피하는 방법을 정리합니다.

---

TL;DR

# 1) pip 최신화
python3 -m pip install -U pip setuptools wheel

# 2) "바이너리 휠만" 설치 강제
PIP_ONLY_BINARY=:all: python3 -m pip install --only-binary=:all: pyarrow

• 이렇게 하면 휠이 있을 때만 설치합니다.
• 휠이 없으면 소스 빌드 시도 없이 실패하므로, 빌드 도구/헤더가 없는 서버에서도 깔끔하게 정리됩니다.

---

왜 소스 빌드로 빠질까?

• 해당 플랫폼/파이썬 버전용 휠이 없음 (예: Linux의 오래된 배포판, Python 3.11용 휠 미제공 버전 등)
• 내부망/프록시로 PyPI 접근이 제한되어 휠을 못 받음
• pip 설정/환경변수로 소스 빌드를 허용해 둔 상태
• 특정 패키지(예: pyarrow)는 C/C++ 의존이 많아 빌드가 매우 무거움 → 실패 확률 ↑

---

옵션 설명: --only-binary

• --only-binary=<패키지목록>: 지정한 패키지는 바이너리 휠만 허용
• --only-binary=:all:: 모든 패키지에 대해 휠만 허용
• 환경변수 버전: PIP_ONLY_BINARY (동일한 효과)

자주 쓰는 패턴

# 전부 휠만
PIP_ONLY_BINARY=:all: pip install --only-binary=:all: <패키지들>

# 특정 패키지만 휠 강제 (예: pyarrow만)
PIP_ONLY_BINARY=pyarrow pip install pyarrow

# 반대로, 전부는 소스 허용하되 특정 패키지만 휠 금지
PIP_NO_BINARY=pyarrow pip install pyarrow   # (거의 안 씀)

---

실전 예시: pyarrow 안전 설치

pyarrow는 소스 빌드 시 Arrow C++까지 얽혀 아주 힘듭니다. 휠만 쓰세요.

# 기본: 최신 3종 버전 순차 시도 (휠만 허용)
PY=/home/cbm/tmp/python3.11.9/bin/python3

$PY -m pip install -U pip setuptools wheel

PIP_ONLY_BINARY=:all: $PY -m pip install --only-binary=:all: "pyarrow==17.0.0" || \
PIP_ONLY_BINARY=:all: $PY -m pip install --only-binary=:all: "pyarrow==16.1.0" || \
PIP_ONLY_BINARY=:all: $PY -m pip install --only-binary=:all: "pyarrow==16.0.0"

# 확인
$PY - <<'PY'
import pyarrow as pa, numpy as np
print("pyarrow", pa.__version__)
print("numpy  ", np.__version__)
PY

버전 다운그레이드는 그 버전에 휠이 존재해서 잘 깔리는 경우가 많습니다.

---

회사/내부망에서 자주 필요한 설정

1) pip 인덱스(미러) & 신뢰 호스트

# 1회 설정 (전역)
pip config set global.index-url http://<내부-미러>/simple
pip config set global.trusted-host <내부-미러-호스트>

# 또는 환경변수로 일시 설정
export PIP_INDEX_URL=http://<내부-미러>/simple
export PIP_TRUSTED_HOST=<내부-미러-호스트>

2) 로컬 휠하우스(오프라인 설치)

외부에서 휠만 미리 다운로드 → 내부로 들여와 설치:

# 외부 PC에서 (휠만 다운로드)
pip download --only-binary=:all: -r requirements.txt -d wheels

# 내부 서버에서 (오프라인 설치)
pip install --no-index --find-links=./wheels -r requirements.txt

---

전역으로 “휠만” 정책 고정하고 싶다면

a) 환경변수로 고정

# bashrc / profile 등에 추가
export PIP_ONLY_BINARY=:all:

b) pip 설정으로 고정

pip config set global.only-binary :all:

팀/서버 표준으로 강제하면 예상치 못한 소스 빌드를 원천 차단할 수 있음.

---

트러블슈팅 체크리스트

1. pip 최신화: 구버전은 새로운 휠을 못 알아먹을 때가 있음

python3 -m pip install -U pip setuptools wheel

2. 플랫폼/파이썬 태그 확인
   pip debug --verbose를 보면 현재 환경이 어떤 휠 태그를 지원하는지 나옴.

pip debug --verbose | sed -n '/Compatible tags/,/End/p' | head -n 30

• 예: manylinux2014_x86_64 cp311 등이 보여야 cp311-manylinux2014_x86_64.whl을 설치 가능

3. 휠 유무 확인
   해당 버전에 내 환경용 휠이 실제로 존재하는지 확인(없으면 버전 조정).

4. 왜 소스 빌드로 갔는지 로그로 보기

pip -v install --only-binary=:all: <패키지>

• “no matching distribution”이면 휠이 없음
• “Ignoring … binary” 같은 문구가 보이면 설정 충돌(only/no-binary) 가능

5. 대안 라이브러리 고려

• Arrow/Parquet만 급하면 fastparquet로 우회:

  pip install fastparquet

---

요구사항 파일에서 쓰는 법

requirements.txt의 맨 위 줄에 옵션을 둘 수 있음.

--only-binary=:all:
pyarrow==16.1.0
pandas==2.2.3
numpy==2.3.4

이렇게 해두면 팀원이 그냥 pip install -r requirements.txt 해도 휠만 설치됨.

---

실제로 많이 보는 오류 예시 & 대응

CMake가 ArrowConfig.cmake를 찾지 못함 (pyarrow 소스 빌드)

CMake Error at CMakeLists.txt:... (find_package):
  Could not find a package configuration file provided by "Arrow"...

→ 휠로 설치:

PIP_ONLY_BINARY=:all: pip install --only-binary=:all: pyarrow

gcc / kernel-headers / openssl / zlib 등 개발 헤더 요구

→ 소스 빌드로 빠졌다는 신호. 휠만 설치하도록 고정하거나, 버전을 바꿔 휠이 있는 버전을 쓰rl.

---

마무리

• 서버/내부망 환경에선 소스 빌드가 비용이 크고 실패 확률 높음
• --only-binary=:all:(혹은 PIP_ONLY_BINARY=:all:)로 휠만 사용하면 대부분의 지뢰를 피할 수 있음.
• 그래도 안 되면 버전 조정(휠 존재 버전) 또는 로컬 휠하우스를 준비.