pip install Failed (tested)

pip install fails for a handful of distinct reasons that get lumped together under "pip install failed": a blocked system Python (PEP 668), a missing compiler or header for a package built from source, a bad TLS certificate, or a package index that isn't reachable. Each needs a different fix. We reproduced four of them on a real Debian 13 box and recorded the exact text pip prints.

1. "externally-managed-environment" (the most common one today)

On Debian, Ubuntu and other distros that follow PEP 668, the system Python ships a marker file (/usr/lib/python3.13/EXTERNALLY-MANAGED on our box) that blocks pip install outside a virtual environment. This is new compared to older tutorials, which is why it confuses people. Running pip install six with the system Python, no venv active, gave us exactly this:

error: externally-managed-environment

× This environment is externally managed
╙─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.13/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Nothing was installed and the system Python was left untouched — pip aborts before touching any files. pip itself suggests three fixes, in order of how safe they are:

• Use a virtual environment (recommended): python3 -m venv .venv && .venv/bin/pip install six. This is the fix that matches how the rest of the Python ecosystem expects you to work.
• Use pipx for installing command-line tools system-wide without touching the interpreter's own site-packages.
• Pass --break-system-packages only if you understand the risk: it can overwrite files apt manages and break system tools that depend on them (apt itself, on Debian, is written in Python). Treat it as a last resort, and reinstall with apt install --reinstall python3-xyz if it breaks something.

2. The fix, proven: same package, in a venv, works

To make the contrast concrete we installed the exact same package in a virtual environment right after the failure above:

$ python3 -m venv /tmp/demo-venv
$ /tmp/demo-venv/bin/pip install six
Collecting six
  Using cached six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)
Installing collected packages: six
Successfully installed six-1.17.0

No flags, no errors. A venv has its own site-packages directory, so it is never "externally managed" and pip will install into it freely. If you only ever see this error in system contexts (a bare pip install with no venv active, or inside a minimal Docker image using the distro's Python), creating a venv — or using a python base image that doesn't apply PEP 668, see below — fixes it for good.

3. "Failed to build wheel for X" / "Failed building wheel for X"

This means pip had to compile a package from source (no prebuilt wheel matched your OS/Python/CPU) and the build failed, usually because a system library or compiler header is missing. We reproduced it with psycopg2 (the PostgreSQL driver, whose source build needs pg_config from libpq, forced with pip install psycopg2==2.9.9 --no-binary :all:):

running egg_info
writing psycopg2.egg-info/PKG-INFO
writing dependency_links to psycopg2.egg-info/dependency_links.txt
writing top-level names to psycopg2.egg-info/top_level.txt

Error: pg_config executable not found.

pg_config is required to build psycopg2 from source.  Please add the directory
containing pg_config to the $PATH or specify the full executable path with the
option:

    python setup.py build_ext --pg-config /path/to/pg_config build ...

or with the pg_config option in 'setup.cfg'.

If you prefer to avoid building psycopg2 from source, please install the PyPI
'psycopg2-binary' package instead.

ERROR: Failed to build 'psycopg2' when getting requirements to build wheel

The fix depends on which library is missing, but the pattern is always the same:

• Read the last 10–15 lines above the "Failed to build" line — the real cause (missing header, missing binary like pg_config, wrong compiler) is always printed just above it.
• Prefer a prebuilt wheel if one exists: here, pip install psycopg2-binary instead of psycopg2 sidesteps the compile entirely.
• Otherwise install the missing system dependency (e.g. apt install libpq-dev for psycopg2, build-essential for a missing compiler) and retry.
• If the package is simply too old for your Python version (no sdist or wheel supports it), the fix is to bump the pinned version instead of fighting the build.

4. SSL certificate errors (per pip/CPython docs, not measured)

We did not stand up a self-signed HTTPS index for this guide, but the three real-world causes are well documented and worth naming directly, since the generic pip._vendor.urllib3...SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] message doesn't tell you which one you have:

• Corporate proxy / firewall TLS inspection (MITM). By far the most common cause on company laptops: the proxy re-signs HTTPS traffic with its own CA, which isn't in Python's trust store. Fix: point pip at the corporate CA bundle with pip config set global.cert /path/to/corp-ca.pem, or set PIP_CERT/REQUESTS_CA_BUNDLE.
• Outdated certifi bundle. pip vendors its own CA list via certifi; an old pip can be missing a newer root cert. Fix: upgrade pip (python -m pip install --upgrade pip) in a venv, or upgrade certifi.
• Clock skew. If the machine's clock is far enough off, certificate validity windows fail even with a correct chain. Check date against real time.

If the exact wording is "self-signed certificate in certificate chain," see our dedicated page: self-signed certificate in certificate chain. For the browser/TLS-handshake version of a broken certificate, see ERR_SSL_PROTOCOL_ERROR.

5. "Failed to establish a new connection" / index unreachable

This is pip saying it can't open a TCP connection to the package index at all — no proxy, no DNS, no listener, or a firewall drop. We pointed pip at a port nothing listens on (--index-url http://127.0.0.1:1/) to get the exact text:

Looking in indexes: http://127.0.0.1:1/
WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError("HTTPConnection(host='127.0.0.1', port=1): Failed to establish a new connection: [Errno 111] Connection refused")': /somepkg-doesnotmatter/
WARNING: Retrying (Retry(total=3, ...)) after connection broken by '...Connection refused...'
WARNING: Retrying (Retry(total=2, ...)) after connection broken by '...Connection refused...'
WARNING: Retrying (Retry(total=1, ...)) after connection broken by '...Connection refused...'
WARNING: Retrying (Retry(total=0, ...)) after connection broken by '...Connection refused...'
ERROR: Could not find a version that satisfies the requirement somepkg-doesnotmatter (from versions: none)
ERROR: No matching distribution found for somepkg-doesnotmatter

pip retries 5 times with backoff before giving up, which is why this error is slow to appear. Common real causes and fixes:

• No internet / DNS failure in CI or Docker. Test with curl -v https://pypi.org from the same shell pip runs in; if that also fails it's a network/DNS problem, not a pip problem.
• A proxy env var is wrong or missing. Check HTTPS_PROXY/HTTP_PROXY are set (or correctly unset) for the shell/container pip runs in.
• A private/internal index URL is misconfigured in pip.conf, PIP_INDEX_URL, or --index-url — a typo'd host or port reproduces exactly the error above.

If you see "Connection refused" from a specific service rather than pip's index, see ERR_CONNECTION_REFUSED / ECONNREFUSED, or the requests-library version in Python requests ConnectionError: Max retries exceeded.

6. "pip install fails in Docker build"

Inside a Docker build, every error above can show up, but two causes are specific to containers:

• Base image has PEP 668 enabled (e.g. debian:trixie, recent python:3.x-slim variants built on Debian). The fix in a Dockerfile is usually to install into a venv baked into the image, or use an official python:3.x image (upstream builds don't apply PEP 668 the way Debian's own python3 package does), rather than reaching for --break-system-packages in a disposable image.
• No network during build (air-gapped CI, missing --network flag, or a build-time secret/proxy not forwarded into the build stage) — this looks exactly like section 5 above.

If the daemon itself is the problem rather than pip, that's a different error: see Docker: Cannot connect to the Docker daemon.

7. Quick diagnosis table

If the failure is actually about the package not existing once it does download, that's a different bug class — see ModuleNotFoundError vs ImportError for what happens after a successful install when the import still fails.

Got SyntaxError: invalid syntax instead? You typed pip at the Python >>> prompt: see pip install SyntaxError: invalid syntax.

Written with AI assistance. Measured on 2026-10-02 on Debian GNU/Linux 13 (trixie) with system Python 3.13.5 and pip 26.2.1 (run from a separate venv at /tmp/py415venv, since this Debian install ships no system-wide pip module). The SSL certificate section is from pip/CPython docs, not measured. PlainHeaders is our extension; curl, Python and pip are free.