pip 23+ · Python
The message
error: externally-managed-environment
What it means
This Python belongs to the operating system or to Homebrew, and pip refuses to write into it (PEP 668). You ran pip install against the system interpreter; the message is telling you to create a virtual environment. --break-system-packages does what its name says — it can leave apt-managed files in a broken state — so make a .venv and install there instead.
The fix
python3 -m venv .venv && source .venv/bin/activate- Printed by
- pip 23+
- Python
- 18
A Python traceback splits the answer in two — the last line says what went wrong, the frames above it say where — so reading only the last line gives you the name and loses the place, and for the value-is-missing errors such as NoneType and KeyError the cause almost always sits in a frame above the one that crashed.
Reading an error message
- Read from the first line down. The lower you go the more it is about the tool’s internals; the cause is usually at the top.
- If there is a file and a line number, start there — not the top stack frame, but the topmost line that names a file you wrote.
- Search the message verbatim, but strip your own paths and variable names first; those are what stop the search from matching.
- The same condition is worded differently across tool versions. If results look wrong, add the version number to the query.
- Before pasting a fix, check what it throws away. Some of these cannot be undone.
Common questions
Q. What does “error: externally-managed-environment” mean?
This Python belongs to the operating system or to Homebrew, and pip refuses to write into it (PEP 668). You ran pip install against the system interpreter; the message is telling you to create a virtual environment. --break-system-packages does what its name says — it can leave apt-managed files in a broken state — so make a .venv and install there instead.
Q. How do I fix it?
python3 -m venv .venv && source .venv/bin/activate — before running it, check the explanation above for what this command discards.
Q. Which tool prints this?
pip 23+. It sits under Python, and the message runs to 2 words.