pip package install failure

What this failure means

pip install could not satisfy one or more package requirements. The package may not exist on PyPI, the version constraint is too restrictive, or a C extension failed to compile.

Symptoms

Faultline looks for one or more of these log fragments:

ERROR: Could not find a version that satisfies the requirement
No matching distribution found for
pip._internal
ResolutionImpossible
Could not build wheels for
error: command 'gcc' failed
Ignored the following versions that require a different python version
requires a different python version

Diagnosis

pip install could not satisfy one or more package requirements. The package may not exist on PyPI, the version constraint is too restrictive, or a C extension failed to compile.

Fix steps

1. Run python -m pip install -r requirements.txt -v in the same interpreter or virtual environment that CI uses, so the resolver output matches the failing job.
2. For ResolutionImpossible: relax or align version constraints in requirements.txt.
3. For Failed building wheel: install the required system libraries (e.g. libpq-dev, build-essential).
4. For private indexes: set PIP_EXTRA_INDEX_URL or add --extra-index-url to the install command.
5. Use pip-compile from pip-tools to generate a locked requirements.txt.

Validation

• Re-run the local reproduction command after the fix.
• python -m pip check passes in the same environment.
• python -m pip install -r requirements.txt completes successfully.

Why it matters

Common causes: conflicting version constraints across packages, a package that requires a native library or compiler toolchain that is not installed, a private PyPI index that is unreachable, or Python version incompatibility.

Prevention

• Use pip-compile or poetry lock to pin all transitive dependencies.
• Cache the pip download cache between CI runs.
• Specify a minimum Python version in pyproject.toml to prevent incompatible installs.

Try it locally

python -m pip install -r requirements.txt -v

How Faultline detects it

Use faultline explain pip-install-failure to see the full playbook.

faultline analyze build.log
faultline explain pip-install-failure

Generated from playbooks/bundled/log/build/pip-install-failure.yaml. Do not edit directly.