pip "Could not find a version that satisfies the requirement" in Docker builds

TL;DR

In Docker builds this error usually means the package index is unreachable or wrong inside the build: no network to PyPI, a private index not configured in the image, or a Python version in the image that the required package does not support. The requirement is fine; the build environment's view of the package world is broken. Check index reachability and Python version first.

The query

pip "Could not find a version that satisfies the requirement" in Docker builds

Use this when

• Docker builds fail on pip install with version errors
• Local pip installs the same requirements fine
• Private package indexes are involved
• Base image Python version changed

Not for when

• Local pip resolution issues
• Version pinning strategy (different topic)
• pip cache corruption

Steps

Step 1: Check network access to the index from the build

Verify the build can reach the package index: corporate proxies, egress firewalls, and build network isolation all block PyPI silently. A quick index query from a debug build confirms or denies connectivity. Expected output: index reachable, or the network block identified.

Step 2: Confirm the Python version supports the requirement

Check the image's Python version against the package's requires-python. Base image updates bump Python versions; packages without wheels for the new version vanish from the resolvable set. Expected output: version compatibility confirmed, or the mismatch found.

Step 3: Configure private indexes inside the build

If you use a private index, ensure the pip config (index URL, credentials) is present during the build, passed securely via build secrets, not baked into layers. A missing index config makes private packages unresolvable. Expected output: private packages resolving with proper index configuration.

Step 4: Check for platform-specific wheels

Some packages only publish wheels for certain platforms; an image on a different architecture (arm64 vs amd64) may find no satisfying version. Check the package's published files for your platform. Expected output: platform availability confirmed, or the architecture mismatch identified.

Step 5: Pin and hash for reproducibility

Once resolved, pin versions and consider hash-checking mode. Unpinned requirements re-resolve on every build and break when the index changes; pins make builds deterministic. Expected output: deterministic installs immune to index drift.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pUGqM-dr7yL7zbLwaJv4vw