Hentikan instalasi ketika hash tidak cocok. Jangan menghapus hash, mematikan TLS, atau mengganti hash yang diharapkan dengan nilai Got hanya agar instalasi lolos. Pip sedang menolak artefak yang byte-nya berbeda dari yang disetujui; penyebabnya bisa salah file/platform, unduhan rusak, konfigurasi index berbeda, atau insiden keamanan.

Arti pesan error

Potongan pesan berikut bersifat ilustratif; digest disingkat dan bukan nilai yang dapat dipakai dalam requirements:

ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE.
    Expected sha256 <hash-yang-disetujui>
         Got        <hash-file-yang-diterima>

Hash adalah sidik jari file distribusi, bukan sekadar nama dan versi paket. Wheel Windows, wheel Linux, dan sdist pada versi yang sama bisa memiliki hash berbeda. Dua unduhan file yang benar-benar identik harus memiliki digest yang sama.

Mode hash-checking dapat diminta lewat --require-hashes; secara default adanya --hash pada satu requirement juga mengaktifkannya untuk seluruh requirements. Semua dependensi transitif harus dikunci ke versi tepat dan memiliki hash yang disetujui. Jangan mengandalkan menghapus satu flag sebagai cara memperbaiki error. Pip juga dapat membandingkan digest dari tautan unduhan index; lihat URL dan konteks log untuk mengetahui sumber hash.

Hash tidak membuktikan suatu paket bebas malware. Jaminannya bergantung pada bagaimana hash awal dan artefak disetujui. Hash dari file yang belum dipercaya tidak boleh menjadi dasar tunggal untuk mempercayai file itu sendiri.

Penyebab yang perlu dibedakan

Temuan Yang diperiksa
Nama/version pin berubah tetapi hash lama tetap ada Riwayat perubahan requirements atau lockfile
Berhasil pada satu platform saja Tag wheel, versi Python, arsitektur, dan environment marker
Hanya gagal melalui cache atau mirror tertentu Unduhan tidak lengkap, cache/proxy, serta sumber artefak
Nama dan versi sama tetapi sumber berbeda Index privat, mirror, direct URL, atau konfigurasi tambahan
Hash berubah tanpa perubahan yang disetujui Hentikan proses dan eskalasi kemungkinan artefak salah atau kompromi

PyPI tidak mengizinkan penggunaan ulang nama file distribusi, termasuk setelah file dihapus. Jadi, “maintainer menimpa file yang sama di PyPI” bukan penjelasan normal. Rilis yang sama dapat memperoleh artefak baru dengan nama berbeda; registry privat dapat mempunyai kebijakan berbeda. Bandingkan nama file lengkap dan asalnya, bukan nomor versi saja.

1. Simpan bukti sebelum mengubah apa pun

Catat nama paket, versi, nama wheel/sdist, Expected/Got, versi Python/pip, OS, dan perintah yang gagal. Salin requirements/lockfile untuk audit. Jangan memublikasikan log mentah yang berisi token, URL berkredensial, nama host internal, atau path sensitif.

Perintah berikut hanya membaca versi dan lokasi cache:

python --version
python -m pip --version
python -m pip cache dir

Gunakan interpreter proyek yang benar; pada Windows, py -m pip dapat digunakan jika launcher mengarah ke interpreter yang dimaksud. Periksa konfigurasi index, extra-index, proxy, dan file konfigurasi secara privat. Jangan beralih dari index organisasi ke PyPI secara sembarang karena nama paket privat bisa bertabrakan dengan paket publik.

2. Ulangi unduhan dengan verifikasi tetap aktif

Dari folder investigasi baru, gunakan requirements yang masih dikunci dan telah ditinjau, termasuk file yang dirujuk lewat -r atau -c. Untuk langkah ini, gunakan hanya requirement nama paket dengan pin versi tepat dan hash; jangan sertakan direct URL, VCS, path lokal, arsip sumber, atau opsi yang menimpa pembatas binary/hash. Dengan prasyarat itu, perintah berikut memilih wheel yang cocok untuk environment saat ini tanpa memasang paket atau menjalankan build backend:

python -m pip download --require-hashes --only-binary=:all: --no-cache-dir --dest ./wheelhouse-investigasi -r requirements.txt
  • --no-cache-dir melewati cache pada percobaan ini, bukan menghapus cache global.
  • --only-binary=:all: membatasi pemilihan distribusi dari index ke wheel, tetapi bukan sandbox. Referensi langsung ke arsip sumber dapat tetap menjalankan build backend walaupun flag ini ada; hash yang benar juga tidak mencegah eksekusi itu. Karena itu, tinjau input sesuai prasyarat di atas. Jika wheel kompatibel tidak tersedia, biarkan pip gagal; jangan melepas pembatas untuk artefak mencurigakan.
  • Perintah memakai sumber paket yang dikonfigurasi. Pastikan sumber itu sesuai kebijakan dan memakai HTTPS.

Jika berhasil tanpa cache, itu petunjuk tentang jalur cache/unduhan, bukan bukti pasti penyebabnya. Jika tetap mismatch, berhenti. Jangan melakukan instalasi tanpa hash sebagai “uji”. Menghapus cache secara rutin juga tidak memperbaiki lockfile salah atau mirror bermasalah.

3. Verifikasi artefak sebelum merevisi lockfile

Bandingkan digest dengan metadata rilis pada sumber tepercaya yang diakses lewat TLS terverifikasi, riwayat lockfile, dan persetujuan pemelihara internal. Pastikan nama file, platform, versi Python, serta sumbernya sama. Bila mencurigai kompromi index, metadata dari index itu sendiri bukan bukti independen; minta verifikasi tim keamanan/pemelihara melalui kanal lain.

Untuk menghitung digest file lokal yang sudah diperoleh melalui proses investigasi yang disetujui, gunakan contoh berikut dengan path file nyata:

python -m pip hash ./wheelhouse-investigasi/nama_paket-1.0.0-py3-none-any.whl

Perintah pip hash hanya menghitung digest; ia tidak mengunduh atau menyatakan file aman. Jangan menyalin hasilnya ke requirements sebelum asal file dikonfirmasi. Satu requirement boleh memuat beberapa hash untuk artefak berbeda yang memang diizinkan. pip download biasa memilih distribusi yang cocok, bukan mengunduh semua varian untuk semua OS.

Jika perubahan dependensi atau platform sudah disetujui, regenerasi lockfile dengan tooling proyek dalam environment terisolasi. Contoh berikut memerlukan pip-tools yang sudah dipasang dan dipin oleh proyek, bukan perintah bawaan pip:

pip-compile --generate-hashes --output-file=requirements.candidate.txt requirements.in

Tinjau diff file kandidat terhadap lockfile lama: versi, sumber, dependensi transitif, dan hash. File kandidat baru dapat menghasilkan versi berbeda karena resolver tidak memakai lock lama sebagai output; jangan menggantinya tanpa review. Resolusi/build metadata sendiri dapat mengeksekusi kode paket jika sdist digunakan, sehingga jalankan hanya terhadap sumber yang telah disetujui dalam sandbox. Uji setiap kombinasi Python/OS yang didukung; pembuatan hash tidak otomatis menyelesaikan perbedaan dependency marker lintas platform.

4. Instal dan verifikasi di virtual environment baru

Sesudah lockfile disetujui dan wheelhouse lengkap, buat virtual environment baru. Ganti nama folder jika sudah ada; jangan memakai environment aplikasi aktif.

python -m venv .venv-verifikasi

Linux/macOS:

.venv-verifikasi/bin/python -m pip install --no-index --find-links=./wheelhouse-investigasi --require-hashes --only-binary=:all: -r requirements.txt
.venv-verifikasi/bin/python -m pip check

Windows PowerShell:

.\.venv-verifikasi\Scripts\python.exe -m pip install --no-index --find-links=./wheelhouse-investigasi --require-hashes --only-binary=:all: -r requirements.txt
.\.venv-verifikasi\Scripts\python.exe -m pip check

--no-index mencegah pencarian index; pastikan requirements tidak memuat direct URL atau referensi VCS bila pengujian harus benar-benar offline. pip check hanya memeriksa kompatibilitas dependensi yang terpasang, bukan memverifikasi ulang hash file instalasi, memindai malware, atau menguji perilaku aplikasi. Hash diverifikasi terhadap arsip saat instalasi. Setelah itu jalankan tes aplikasi yang relevan dalam sandbox.

Uji negatif dan kriteria selesai

Untuk menguji mekanisme hash tanpa mengambil paket eksternal, gunakan wheel dummy yang dibuat lokal dalam direktori sementara. Buat requirements fixture dengan hash SHA-256 benar, lalu salinan dengan satu karakter digest diubah. Jalankan instalasi dry-run dengan index dimatikan, wheel-only, dan cache terpisah. Fixture benar harus diterima; fixture salah harus ditolak dengan hash mismatch. Jangan mengubah lockfile produksi untuk uji negatif.

Batas pengujian review: pada pip 26.2.1/Python 3.11, wheel dummy lokal dengan hash benar diterima oleh dry-run, sedangkan hash salah ditolak. Fixture tambahan berupa sdist buatan sendiri menunjukkan bahwa referensi sumber langsung dengan hash benar masih dapat memanggil build backend meskipun memakai --only-binary=:all:. Tidak ada paket pihak ketiga atau dependensi proyek yang dipasang. Unduhan registry, regenerasi pip-tools, instalasi venv, dan tes aplikasi di atas belum dijalankan untuk proyek pembaca.

Pengujian itu membuktikan bahwa kontrol hash bekerja, bukan membuktikan keamanan paket proyek. Insiden dianggap selesai setelah sumber perbedaan dipahami, perubahan lockfile disetujui, unduhan/instalasi dengan hash tetap aktif berhasil, dan tes aplikasi lulus. Bila asal perubahan tidak dapat dijelaskan, pertahankan kegagalan instalasi dan eskalasi.

Referensi