pip error: externally-managed-environment (tested)

error: externally-managed-environment means your Linux distribution marks its system Python as managed by apt (PEP 668), so pip install and pip install --user refuse to touch it. Create a virtual environment (python3 -m venv .venv) and install there, or use apt install python3-xyz or pipx.

1. Reproduce it, and the fixes that work

A fresh debian:trixie-slim container (Debian 13, Python 3.13.5, pip 25.1.1), running this script as root (set -x prints each command):

set -x
apt-get update -qq >/dev/null && apt-get install -y -qq python3 python3-pip python3-venv >/dev/null 2>&1
python3 --version; pip3 --version
pip3 install selenium 2>&1 | head -30
python3 -m venv /tmp/v && /tmp/v/bin/pip install -q selenium && /tmp/v/bin/python -c "import selenium; print('venv OK', selenium.__version__)"
pip3 install --user selenium 2>&1 | tail -2
apt-get install -y -qq python3-selenium >/dev/null 2>&1 && python3 -c "import selenium; print('apt python3-selenium', selenium.__version__)"

Output:

+ apt-get update -qq
+ apt-get install -y -qq python3 python3-pip python3-venv
+ python3 --version
Python 3.13.5
+ pip3 --version
pip 25.1.1 from /usr/lib/python3/dist-packages/pip (python 3.13)
+ pip3 install selenium
+ head -30
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.
+ python3 -m venv /tmp/v
+ /tmp/v/bin/pip install -q selenium
+ /tmp/v/bin/python -c import selenium; print('venv OK', selenium.__version__)
venv OK 4.51.0
+ pip3 install --user selenium
+ tail -2
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.
+ apt-get install -y -qq python3-selenium
+ python3 -c import selenium; print('apt python3-selenium', selenium.__version__)
apt python3-selenium 4.31.1

Debian 12+, Ubuntu 23.04+, Raspberry Pi OS (Bookworm) and other distributions ship a marker file, EXTERNALLY-MANAGED, next to the system Python (PEP 668). pip sees it and refuses to install into the system interpreter, because a pip-installed package can overwrite or break one that apt manages. pip install --user is refused too. It is not a bug in the package you are installing; selenium here is just an example.

What works, in order of preference:

1. A virtual environment for your project: python3 -m venv .venv, then .venv/bin/pip install ... and run your code with .venv/bin/python (or source .venv/bin/activate first). Inside a venv the error never appears. This installed Selenium 4.51.0.
2. The distribution package, if one exists: apt install python3-selenium worked without pip, but gave Selenium 4.31.1, older than PyPI's 4.51.0. Distribution packages lag behind.
3. pipx for command-line apps (block 2).

2. venv needs python3-venv; --break-system-packages; pipx

A second fresh container with only python3-pip installed:

apt-get update -qq >/dev/null && apt-get install -y -qq python3-pip >/dev/null 2>&1
echo '$ ls /usr/lib/python3.13/EXTERNALLY-MANAGED'; ls /usr/lib/python3.13/EXTERNALLY-MANAGED
echo '$ python3 -m venv .venv   # python3-venv not installed'; cd /tmp; python3 -m venv .venv 2>&1 | head -6
echo '$ pip3 install --break-system-packages requests'; pip3 install -q --break-system-packages requests 2>&1 | tail -1
python3 -c "import requests; print(requests.__file__)"
echo '$ PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install six'; PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install -q six 2>&1 | tail -1; python3 -c "import six; print(six.__file__)"
apt-get install -y -qq pipx >/dev/null 2>&1; echo '$ pipx install httpie'; pipx install httpie 2>&1 | tail -3

Output:

$ ls /usr/lib/python3.13/EXTERNALLY-MANAGED
/usr/lib/python3.13/EXTERNALLY-MANAGED
$ python3 -m venv .venv   # python3-venv not installed
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.13-venv

$ pip3 install --break-system-packages requests
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
/usr/local/lib/python3.13/dist-packages/requests/__init__.py
$ PIP_BREAK_SYSTEM_PACKAGES=1 pip3 install six
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
/usr/local/lib/python3.13/dist-packages/six.py
$ pipx install httpie
    - man1/http.1
    - man1/httpie.1
    - man1/https.1

• python3 -m venv fails with ensurepip is not available until you apt install python3-venv (or python3.13-venv); see venv: ensurepip is not available.
• --break-system-packages (or the environment variable PIP_BREAK_SYSTEM_PACKAGES=1) overrides the check. As root, the package went to /usr/local/lib/python3.13/dist-packages, outside apt's own /usr/lib/python3/dist-packages, but it can still shadow an apt-installed version of the same package for every program on the system. Acceptable in a throwaway container; avoid it on a machine you care about.
• pipx install httpie put the app in its own virtual environment and linked its commands (the end of its output is shown). Use pipx for tools you run from the shell, not for libraries you import.

3. In a Dockerfile

On a Debian or Ubuntu base image, either create a venv in the image (RUN python3 -m venv /opt/venv and ENV PATH=/opt/venv/bin:$PATH) or use the official python:3 images: their Python lives in /usr/local, has no marker file, and pip install works as before.

Related: installing Jupyter on Debian/Ubuntu, uv pip install vs uv add · pip install failed · pip subprocess-exited-with-error · pip install SyntaxError. If the failing command was pip install poetry, see Poetry error: externally-managed-environment. In a Dockerfile: Docker pip externally-managed-environment.

Written with AI assistance. Measured on 2026-10-23 in debian:trixie-slim containers (Debian 13, Python 3.13.5, pip 25.1.1). Each script was run verbatim and the output pasted unedited (only Docker's image-pull lines removed). PlainHeaders is our extension; Python, pip and Debian are free.