Hash‑Based Integrity Verification in pip for PyPI Packages

Problem and Takeaway

When installing a package from PyPI, pip must ensure the downloaded file matches the expected SHA‑256 hash recorded in its metadata. Without this check, a malicious or corrupted package could be installed, breaking automated workflows.

Requirements

The smallest design that satisfies trust and operational needs includes:

• Hash values recorded in package metadata (PKG-INFO) as specified by PEP 508 and PEP 610.
• pip version ≥ 20.1 that enforces verification for all PyPI downloads in virtual environments or when a cache is used.
• A secure source for the expected digest (e.g., CI pipeline, developer‑provided command line).

Design Overview

Hash verification creates a trust boundary: PyPI is considered untrusted, while the hash value itself is trusted because it was recorded by the consumer or CI system. This separation prevents tampering after the hash is set.

Smallest Suitable Design

1. During package upload, the author (or CI) computes sha256sum of the wheel or sdist and embeds it in the PKG-INFO file.
2. pip reads the PKG-INFO, extracts each file’s expected hash, and compares it to the hash of the downloaded file.
3. If any hash does not match, pip aborts the installation and returns a non‑zero exit status.

Operational Checks

To verify that hash verification is active, run a dry‑run install or inspect the RECORD file of the downloaded wheel:

# Dry‑run (no state change)
pip install --dry-run 

If the command succeeds, the hashes matched; if it fails, the mismatch is reported before any files are written.

Alternatively, after downloading a wheel manually, compute its SHA‑256 and compare:

sha256sum mypackage‑1.0.0‑py3-none-any.whl

The resulting hash must equal the value shown in the install command’s --hash=sha256:'' argument or in the CI configuration.

Version‑Sensitive Behavior

Python 3.8+ with pip 20.1+ enforces hash checks for all PyPI downloads; older pip versions only warn when a hash is missing or incorrect, allowing installation to continue. This difference is critical when scripting installations across heterogeneous environments.

Failure Modes and Conditions Changing the Design

• Missing or malformed hash entries in PKG-INFO cause immediate aborts with pip 20.1+, while older pip versions may still install.
• If the expected digest is stored only in a CI script and the script is altered, the trust boundary is broken, allowing tampered packages to pass verification.
• Running pip without a virtual environment or cache may bypass enforcement in some configurations, reducing security.

Practical Verification Workflow

1. Obtain the expected SHA‑256 from your CI pipeline or developer‑provided command line (placeholder <hash>).
2. Run pip install with the --hash=sha256:'' flag to enforce verification for a single package.
3. If the install fails, compare the downloaded wheel’s hash (using sha256sum) with the expected value to locate the mismatch.
4. Update the stored hash in the PKG-INFO or CI configuration and re‑run the install to confirm success.

Limitations

Hash verification relies on the integrity of the originally recorded digest; if that value is lost or corrupted, the security benefit disappears. Additionally, packages without a wheel (source distributions) require the hash of the built artifact, which may not be present until after build time.

Conclusion

Hash‑based integrity verification in pip provides a concrete, PEP‑specified trust boundary that protects automated workflows from tampered PyPI packages. By ensuring the correct pip version, securely storing expected hashes, and routinely checking the RECORD file or using dry‑run mode, teams can reliably enforce this security measure.