How to fix the "externally-managed-environment" error
Running pip install on a system Python protected by PEP 668 produces this error:
error: externally-managed-environment
× This environment is externally managedThe fix depends on what was being installed.
Installing project dependencies
Use uv to create a project with its own virtual environment:
$ uv init my-project
$ cd my-project
$ uv add requests
Without uv, create a virtual environment manually:
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install requests
Installing command-line tools
Tools like ruff, black, or httpie should be installed in isolated environments rather than system-wide. Use uv tool install or pipx:
$ uv tool install ruff
$ ruff check .
Overriding the protection
The --break-system-packages flag tells pip to ignore the marker:
$ pip install --break-system-packages requests
The environment variable PIP_BREAK_SYSTEM_PACKAGES=1 does the same thing permanently when set in a shell profile.
Warning
Overriding is reasonable inside containers and CI environments where the system Python is disposable. On a desktop or server Linux installation, it risks breaking OS tools that depend on system-managed packages.
Learn More
- What is PEP 668?
- What is a virtual environment?
- How to install Python with uv
- How to require a virtualenv when installing packages with pip
Also Mentioned In
Get Python tooling updates
Subscribe to the newsletter