Troubleshooting

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

pip 22.0 and later print most failures as a diagnostic error: a short reference name after error:, a × line saying what failed, a ╰─> line with the cause, and note:/hint: lines. The reference names are stable, so you can search for them. This page lists them for pip 26.2.2, with real output wherever the error could be produced on CPython 3.14.6 on 2026-10-22; the message texts that could not be triggered are quoted from the pip 26.2.2 source, src/pip/_internal/exceptions.py. Scratch paths are shortened to ….

The error references

Reference Meaning First thing to try

Reference	Meaning	First thing to try
`externally-managed-environment`	PEP 668: the target Python belongs to the operating system or another tool.	Use a venv. See Environments.
`subprocess-exited-with-error`	A build backend subprocess (metadata, wheel or editable build) failed.	Read the backend’s own output above the error.
`metadata-generation-failed`	The backend could not produce metadata for a package.	Same; often an invalid `pyproject.toml` or a missing build tool.
`failed-wheel-build-for-install`	One or more packages could not be built into wheels.	Missing compiler or headers, or an sdist incompatible with your Python. Prefer a wheel (`--only-binary`).
`failed-build-dependency-install`	Installing the `[build-system] requires` into the isolated build environment failed.	Check the build requirements and your index; see `--build-constraint`.
`missing-pyproject-build-system-requires`	`[build-system]` without `requires`.	Fix the project’s `pyproject.toml`.
`invalid-pyproject-build-system-requires`	`requires` is not a list of valid requirement strings.	Same.
`ssl-verification-failed`	TLS verification failed while downloading a file.	Trust the right CA (system store, `--cert`); see Certificates.
`ssl-missing`	The Python has no `ssl` module.	Use a Python built with OpenSSL.
`proxy-connection-failed`	The configured proxy refused or did not answer.	Check `--proxy` and the `*_proxy` variables.
`connection-failed`, `connection-timeout`	The server could not be reached, or did not answer in time.	Network, DNS, firewall; `--timeout`, `--retries`.
`incomplete-download`	A download ended early and could not be resumed.	Retry; raise `--resume-retries`.
`uninstall-no-record-file`	The installed package has no `RECORD`.	Reinstall with `--ignore-installed --no-deps`, then uninstall.
`uninstall-distutils-installed-package`	The package was installed by distutils and cannot be uninstalled safely.	Remove it by hand or with the tool that installed it.
`invalid-installed-package`	An installed package’s metadata has an invalid requirement or version.	Reinstall or remove it.
`invalid-egg-fragment`	An `#egg=` fragment that is not a bare project name.	Use `name[extra] @ URL`.
`resolution-too-deep`	The resolver exceeded its search depth.	Narrow versions; see Dependency Resolution.
`venv-creation-error`, `venv-import-error`	pip could not create a virtual environment, or import the standard library’s `venv` (a broken or modified Python); used by the experimental `venv-isolation` builds.	Check the Python installation; antivirus software can also interfere.

externally-managed-environment

PEP 668: the target Python belongs to the operating system or another tool.

Use a venv. See Environments.

subprocess-exited-with-error

A build backend subprocess (metadata, wheel or editable build) failed.

Read the backend’s own output above the error.

metadata-generation-failed

The backend could not produce metadata for a package.

Same; often an invalid pyproject.toml or a missing build tool.

failed-wheel-build-for-install

One or more packages could not be built into wheels.

Missing compiler or headers, or an sdist incompatible with your Python. Prefer a wheel (--only-binary).

failed-build-dependency-install

Installing the [build-system] requires into the isolated build environment failed.

Check the build requirements and your index; see --build-constraint.

missing-pyproject-build-system-requires

[build-system] without requires.

Fix the project’s pyproject.toml.

invalid-pyproject-build-system-requires

requires is not a list of valid requirement strings.

Same.

ssl-verification-failed

TLS verification failed while downloading a file.

Trust the right CA (system store, --cert); see Certificates.

ssl-missing

The Python has no ssl module.

Use a Python built with OpenSSL.

proxy-connection-failed

The configured proxy refused or did not answer.

Check --proxy and the *_proxy variables.

connection-failed, connection-timeout

The server could not be reached, or did not answer in time.

Network, DNS, firewall; --timeout, --retries.

incomplete-download

A download ended early and could not be resumed.

Retry; raise --resume-retries.

uninstall-no-record-file

The installed package has no RECORD.

Reinstall with --ignore-installed --no-deps, then uninstall.

uninstall-distutils-installed-package

The package was installed by distutils and cannot be uninstalled safely.

Remove it by hand or with the tool that installed it.

invalid-installed-package

An installed package’s metadata has an invalid requirement or version.

Reinstall or remove it.

invalid-egg-fragment

An #egg= fragment that is not a bare project name.

Use name[extra] @ URL.

resolution-too-deep

The resolver exceeded its search depth.

Narrow versions; see Dependency Resolution.

venv-creation-error, venv-import-error

pip could not create a virtual environment, or import the standard library’s venv (a broken or modified Python); used by the experimental venv-isolation builds.

Check the Python installation; antivirus software can also interfere.

Source: pip 26.2.2 source: exceptions.py.

Build errors

subprocess-exited-with-error and metadata-generation-failed (an invalid version in pyproject.toml), and missing-pyproject-build-system-requires, are shown in full on Build System Interface. A failure during the wheel build itself, here a setuptools project whose C extension source is missing, ends like this:

      running build_ext
      building 'fastbirds._count' extension
      cc -pthread … -c fastbirds/_count.c -o build/temp.linux-x86_64-cpython-314/fastbirds/_count.o
      cc1: fatal error: fastbirds/_count.c: No such file or directory
      compilation terminated.
      error: Command '['cc', '-pthread', …]' returned non-zero exit status 1.
      [end of output]
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for fastbirds
Failed to build fastbirds
error: failed-wheel-build-for-install
× Failed to build installable wheels for some pyproject.toml based projects
╰─> fastbirds

The useful line is the backend’s, inside the indented block (cc1: fatal error: …). On a real sdist from PyPI the usual causes are a missing compiler (cc, MSVC), missing development headers for a C library, or a release that has no wheel for a very new Python yet; installing a version that has a wheel (pip install --only-binary :all: …) is often the quickest fix.

Source: pip 26.2.2 source: exceptions.py, pip install: --only-binary.

Network errors

error: connection-failed

× Failed to connect to localhost while fetching http://localhost:9/tomli_w-1.2.0-py3-none-any.whl
╰─> [Errno 111] Connection refused

hint: Are you connected to the Internet? If so, check whether your system can connect to localhost before trying again. There may be a firewall or proxy that's preventing the connection.

ssl-verification-failed and proxy-connection-failed are on Authentication, Proxies & Certificates. For index pages pip does not raise these errors: it logs Could not fetch URL … - skipping and carries on, which usually ends in the "could not find a version" error below. Run with -v to see those lines.

Source: pip 26.2.2 source: exceptions.py, pip: --verbose.

Install and uninstall errors

externally-managed-environment is on Environments & Externally Managed Pythons and uninstall-no-record-file on Managing Installed Packages. The egg fragment error, for -e "git+file:///…/birdwatch-mono@v0.1.0#egg=birdtally[pretty]&subdirectory=libs/birdtally":

error: invalid-egg-fragment

× The 'birdtally[pretty]' egg fragment is invalid
╰─> from 'git+file:…/git/birdwatch-mono@v0.1.0#egg=birdtally[pretty]&subdirectory=libs/birdtally'

hint: Try using the Direct URL requirement syntax: 'name[extra] @ URL'

Source: pip 26.2.2 source: exceptions.py, pip: VCS URL fragments.

"Could not find a version that satisfies the requirement"

The pair

ERROR: Could not find a version that satisfies the requirement <requirement> (from versions: …)
ERROR: No matching distribution found for <requirement>

means that after filtering, no file was left. The from versions: list tells you which case you are in:

Symptom Likely cause

Symptom	Likely cause
`(from versions: none)`	The name is wrong or misspelled; the index is wrong or unreachable (look for `Could not fetch URL` with `-v`); the index needs credentials; every file was excluded by `--only-binary`, platform options or `Requires-Python`.
A list that stops below what you asked for	The newer versions require a newer Python (`Requires-Python`), have no wheel for your platform, are pre-releases, are yanked (`Ignored the following yanked versions:` is printed), or were hidden by `--uploaded-prior-to`.
A list that contains the version	A conflict with another requirement or constraint; the resolver’s `ResolutionImpossible` message explains it.

(from versions: none)

The name is wrong or misspelled; the index is wrong or unreachable (look for Could not fetch URL with -v); the index needs credentials; every file was excluded by --only-binary, platform options or Requires-Python.

A list that stops below what you asked for

The newer versions require a newer Python (Requires-Python), have no wheel for your platform, are pre-releases, are yanked (Ignored the following yanked versions: is printed), or were hidden by --uploaded-prior-to.

A list that contains the version

A conflict with another requirement or constraint; the resolver’s ResolutionImpossible message explains it.

The "ignored versions" lines are printed just before the error when they apply:

Ignored the following yanked versions: …
Ignored the following versions that require a different python version: …

Source: pip: Dependency resolution, getting help, pip user guide: Watch out for.

`pip debug`

pip debug prints the environment pip sees: its version and Python, the encoding, the certificate configuration, the vendored library versions and, with --verbose, all compatible wheel tags. Its documentation calls the options and the output provisional, and pip prints a warning not to parse it:

python -m pip debug

WARNING: This command is only meant for debugging. Do not use this with automation for parsing and getting these details, since the output and options of this command may change without notice.
pip version: pip 26.2.2 from …/bsi/.venv/lib/python3.14/site-packages/pip (python 3.14)
sys.version: 3.14.6 (main, Jul 18 2026, 17:01:31) [Clang 22.1.3 ]
sys.executable: …/bsi/.venv/bin/python
sys.getdefaultencoding: utf-8
sys.getfilesystemencoding: utf-8
locale.getencoding: UTF-8
sys.platform: linux
…

The tag list answers "why does pip not pick this wheel?". It accepts the same --platform, --python-version, --implementation and --abi options as pip download:

python -m pip debug --verbose | sed -n '/Compatible tags/,+3p'
python -m pip debug --platform win_amd64 --python-version 3.13 | sed -n '/Compatible tags/,+3p'

Compatible tags: 1226
  cp314-cp314-manylinux_2_39_x86_64
  cp314-cp314-manylinux_2_38_x86_64
  cp314-cp314-manylinux_2_37_x86_64
Compatible tags: 45 (target: platforms=['win_amd64'] version_info='3.13')
  cp313-cp313-win_amd64
  cp313-abi3-win_amd64
  cp313-none-win_amd64

A wheel whose tags are not in the list is never chosen. The tags are explained on Building sdists & Wheels.

Source: pip debug.

More output: `-v`, `-vvv` and `--log`

-v shows the Could not fetch URL and link-evaluation lines that explain most "not found" errors, -vv adds HTTP requests, -vvv everything. --log pip.log writes the maximum-verbosity log to a file regardless of the console level, which is what to attach to a bug report together with the exact command and python -m pip --version.

Shell completion: `command not found: compdef`

If zsh prints command not found: compdef at start-up after you appended pip completion --zsh to ~/.zshrc, completion was not initialised before the snippet runs; add autoload -Uz compinit && compinit above it. See Running pip & General Options.

Help from the pip project

The pip documentation’s "getting help" section points to the issue tracker and the Python Discourse; the UX research and design pages describe how the project studies these error messages with users.