requirements에 버전을 고정했는데 해시도 필요한 이유

버전 선택 뒤에도 설치를 허용할 배포 파일을 정해야 합니다. A·B·C는 실제 해시가 아닌 설명용 표기입니다.

requirements의 ==는 패키지 버전을 고릅니다. --hash는 그 버전으로 배포된 파일 중 설치를 허용할 파일을 고릅니다. CI에서 승인한 파일만 설치하려면 하위 의존성까지 고정하고 --require-hashes로 설치하세요.

버전은 같은데 해시가 다르다는 오류가 났다면 파일 이름부터 비교하면 됩니다. Mac용 wheel을 검토하고 Linux CI를 돌린 경우에는 서로 다른 파일이 선택될 수 있습니다. 해시를 다시 적기 전에 이 차이를 설명할 수 있어야 합니다.

하나의 버전에 여러 파일이 붙습니다

설명용 패키지 sample-package 1.2.0을 생각해 보겠습니다. 같은 릴리스에 Mac용 wheel, Linux용 wheel, 소스 압축 파일이 들어 있다면 버전은 하나이고 배포 파일은 셋입니다. 서로 다른 내용의 파일이므로 각 해시도 별도로 관리합니다.

여기서 requirements에 sample-package==1.2.0만 적으면 1.3.0으로 올라가는 일은 막을 수 있습니다. 어느 파일을 고를지는 실행 환경과 설치 옵션에 따라 남아 있습니다. pip의 반복 설치 안내도 버전 고정, 해시 검증, 설치 파일 묶음을 서로 다른 단계로 설명합니다.

예를 들어 개발 환경에서 검토한 Mac wheel의 해시 하나를 기록했다고 합시다. Linux CI가 Linux wheel을 선택하면 허용 목록에 그 파일이 없어 검사가 멈출 수 있습니다. 이 경우 필요한 변경은 ‘해시 검사를 끄기’가 아니라 Linux 배포 파일도 검토 대상에 넣을지 결정하는 일입니다. 두 환경을 지원하려면 각 파일의 해시를 허용하고, 한 환경만 배포한다면 파일 집합을 그 환경에 맞춰 좁힙니다.

해시를 만드는 작업과 승인하는 작업

먼저 배포 대상의 Python 버전·운영체제·CPU 아키텍처를 정하고 사용할 배포 파일을 확보합니다. 아래는 검토할 파일을 sample.whl로 표시한 명령 형태입니다. 내려받기와 설치는 이 글에서 실행하지 않았습니다.

python -m pip hash \
  ./artifacts/sample.whl

pip hash는 로컬 파일의 해시를 계산합니다. 출력된 SHA-256을 해당 요구사항의 --hash=sha256:...에 넣습니다. 본문에 임의의 64자리 숫자를 제공하지 않은 이유는 독자가 실제 파일에서 얻은 값을 사용해야 하기 때문입니다.

계산 전에 파일 출처와 버전이 의도한 것인지 검토해야 합니다. 잘못된 파일을 먼저 받아 그 해시를 승인하면 이후에도 같은 잘못된 파일을 받아들이게 됩니다. 해시가 맞는다는 결과는 기준 파일과 받은 파일이 일치한다는 설명이며, 코드의 취약점이나 악성 동작을 검사한 결과는 아닙니다.

PyPI 다운로드 주소에 붙은 해시만으로 이 준비를 대신할 수도 없습니다. --require-hashes는 requirements에 기록한 로컬 기준을 요구합니다. 다운로드 서버가 전달한 값과 내가 승인해 보관한 값은 출처가 다르기 때문입니다. pip의 로컬 해시 요구사항

최상위 패키지만 적으면 설치가 멈춥니다

sample-package가 sample-helper를 필요로 한다고 가정하겠습니다. 첫 패키지의 버전과 해시만 적으면 helper의 어떤 파일을 허용할지 아직 정하지 않은 상태입니다. 전체 해시 검증 모드에서는 하위 의존성도 명시하고 고정해야 합니다.

설치 명령은 배포 스크립트에 분명하게 남기는 편이 좋습니다.

python -m pip install \
  --require-hashes \
  -r requirements.txt

이 명령에서 의존성이 빠졌다는 오류와 해시가 다르다는 오류는 조치가 다릅니다. 전자는 전체 설치 목록을 완성해야 하고, 후자는 선택된 파일과 승인한 파일을 대조해야 합니다. 둘을 구분하지 않고 오류에 나온 값을 requirements에 붙여 넣으면 승인 기록의 의미가 흐려집니다.

pip 26.2에는 --no-require-hashes로 자동 전체 검증을 해제하는 옵션도 있습니다. 일부 항목의 해시만 검사하는 설정이므로 위 명령과 같은 보장을 기대하면 안 됩니다. 이 글은 2026년 9월 28일 확인한 pip 26.2.1 문서 기준입니다.

소스 빌드를 허용할지도 정합니다

wheel만 허용하려면 설치에 --only-binary :all:을 추가할 수 있습니다. 대상 환경용 wheel이 없으면 설치는 실패합니다. 이는 소스 빌드를 피하기로 한 정책에 맞는 실패이며, 곧바로 제한을 해제할 이유는 아닙니다.

반대로 소스 배포본을 허용하면 같은 입력 파일로부터 빌드하는 과정이 생깁니다. 컴파일러나 시스템 라이브러리까지 requirements 해시가 고정하는 것은 아닙니다. 로컬에서 만들어 캐시한 wheel도 pip는 원래 소스 배포본의 해시를 기준으로 확인하는 동작을 설명합니다. 소스 배포와 캐시의 처리

오프라인 설치가 필요하다면 허용한 파일 자체도 보관해야 합니다. 해시 문자열은 파일을 대신하지 않습니다. pip의 wheelhouse 방식으로 파일을 묶을 수 있지만, 컴파일된 wheel의 플랫폼 호환 범위를 함께 기록해야 합니다.

CI가 해시 오류로 멈췄을 때는 받은 파일 이름, 대상 환경, requirements의 허용 해시를 나란히 놓으세요. 새 플랫폼 파일이 필요한 것인지, 파일이 예상과 달라진 것인지 확인한 뒤 승인 목록을 갱신하면 됩니다.