Pip Hash-Checking: Approve Exact Artifacts, Not Just Version Names

A pinned Python dependency version narrows what a deployment may install, but the version name alone does not identify every acceptable distribution file. A package release can provide several wheels and a source archive. Pip hash-checking adds an explicit contract about the artifact bytes the installation is allowed to accept.

The pip secure-installation guide describes local hashes in requirements files, complete dependency coverage, and the option to disallow source distributions. Hash checking helps detect unexpected artifacts and remote tampering, but it does not prove that an approved package is harmless. The security decision still begins with choosing and reviewing the dependency.

Define the installation target

Record the Python version, operating system, CPU architecture, and package index used for the supported deployment. These details influence which wheel or source distribution pip selects. A requirements file tested on one developer laptop may not cover every deployment platform.

Use a clean, disposable environment for validation. An existing environment can hide missing dependencies because they are already installed. The installation should prove that the reviewed requirements are sufficient on their own.

Identify who updates the dependency contract and how changes are reviewed. A hash mismatch during deployment should have an owner and an investigation path, not trigger an automatic script that fetches a new hash and accepts it without review.

Pin the complete dependency set

Hash-checking mode requires all requirements and dependencies to be explicitly included and hashed. The guide also requires them to be pinned, for example with exact versions rather than a broad compatible range.

Include transitive dependencies as well as the packages the application imports directly. Otherwise, a resolver can need a dependency that the requirements file has not authorized, causing the checked installation to fail.

Keep the resolved set tied to the supported target environment. Environment markers and platform-specific dependencies can complicate a shared file. Test the actual supported combinations rather than assuming one resolution is a universal dependency graph.

Obtain hashes through a reviewed process

Pip's guide recommends strong hashes such as SHA-256. Store the accepted hash values with the requirements under version control so changes can be reviewed alongside version changes.

A hash is meaningful only in relation to the artifact you decided to trust. Downloading an arbitrary file and hashing it faithfully records that file's identity; it does not establish that the file came from the intended publisher or contains acceptable code.

Review the source of the package, the selected distribution, and any relevant security or maintenance concerns before approving its hash. Avoid copying values from an unverified forum or treating the first artifact returned by a compromised source as automatically authoritative.

Enforce checking in the deployment command

The documented --require-hashes option makes the installation requirement explicit. An illustrative command is:

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

This assumes requirements.txt is a reviewed, completely pinned file containing the appropriate hashes. It is not a command to run against an arbitrary file copied from the internet. Use the intended Python environment and approved package source.

The guide explains that supplying a hash for a requirement normally enables hash-checking mode globally. Nevertheless, an explicit flag in the deployment workflow makes the contract visible and helps prevent a future edit from quietly removing checking. Verify behavior with the installed pip version.

Handle multiple distribution files deliberately

One package version can have different artifact hashes for different platform wheels. Pip allows multiple accepted hashes per package so a supported installation can select among the authorized distributions.

Add only the artifacts needed by the supported workflow or justified compatibility requirements. A long hash list copied without understanding its platforms can make review harder and broaden the accepted set unnecessarily.

Test each deployment target using the reviewed file. A missing platform wheel should produce an understandable failure or a deliberate build decision. It should not cause the pipeline to drop hash checking because a developer's machine happened to use another artifact.

Decide whether source builds are allowed

The secure-installation guide recommends --only-binary :all: when the workflow intends to disallow source distributions. This separates the decision to install approved wheels from the decision to execute a source build.

An illustrative wheel-only installation is:

python -m pip install --require-hashes --only-binary :all: -r requirements.txt

Not every dependency provides a compatible wheel for every environment. Test availability before making this an enforced deployment requirement. If a source build is necessary, review the build environment and its dependencies as another part of the supply chain rather than pretending the source hash describes every build input.

Distinguish index hashes from local approval

Package indexes may publish hashes for their files, which can support transfer integrity checks. Pip's guide distinguishes those remotely supplied hashes from the locally recorded hashes required by --require-hashes.

If an attacker controls the artifact source and its reported hash, the two can be changed together. A reviewed local requirement provides an independent expectation about which artifact is allowed at deployment time.

Keep that distinction visible when designing mirrors or caches. Transport encryption and an index-provided checksum are useful, but neither replaces the application team's accepted artifact list. The deployment should validate against the intended local contract.

Understand cache behavior before troubleshooting

The pip guide notes that hash-checking can use the locally built wheel cache. In that case, pip checks the original source distribution hash associated with the cached wheel through recorded origin information.

Do not assume that every checked installation necessarily downloaded a fresh wheel directly from the index. Inspect the relevant cache and build history when the provenance of an installed artifact matters to your workflow.

Prefer a controlled clean-environment test when diagnosing a mismatch or unexpected installation path. Avoid deleting shared caches indiscriminately during an outage. Establish which artifact was selected, where it came from, and why it was or was not authorized.

Make failures informative, not permissive

When checking fails, compare the requested version, selected platform artifact, approved hash list, and configured source. The cause may be a missing legitimate distribution, a changed resolution, a corrupted transfer, or a source that deserves investigation.

Do not fix every failure by removing the flag or adding whatever hash the latest download reports. That turns an enforcement control into an automated approval mechanism. Review the underlying change first.

Keep diagnostics free of repository credentials and private tokens. Index URLs and environment settings can contain sensitive data. Share sanitized artifact names and error context with the appropriate dependency owner while preserving restricted evidence where needed.

Treat dependency updates as new approvals

Updating a pinned version and its hashes is a change to the accepted dependency set. Review release notes, compatibility, and relevant advisories, then validate the clean installation and the application's important tests.

Hash checking does not automatically keep dependencies current. A perfectly reproducible installation of an old vulnerable package remains vulnerable. Pair reproducibility with an owned update and remediation process.

Retain enough information to rebuild approved releases while keeping obsolete dependency sets out of new deployments. The release record should connect source code, requirements, target platform, and test outcome without requiring future maintainers to guess which artifacts were used.

Verify the result at the application layer

After a checked installation, run the application's representative tests and inspect the installed dependency versions through supported tools. Artifact acceptance is one step toward a working release, not proof that the program behaves correctly.

Repeat the clean-install test when Python, pip, platform architecture, or index configuration changes. Those changes can alter artifact selection even if application source remains unchanged.

Pip hash-checking is most valuable as a deliberate artifact boundary: complete pins, reviewed hashes, supported distributions, explicit enforcement, and informative failure handling. It narrows what gets installed while leaving package trust, build security, and application verification as responsibilities the team must still own.