When you use pip to install Python packages, you may encounter an externally-managed-environment error. This error occurs because your Python environment is “externally managed” by a package manager, which prevents direct use of pip for system-wide installations to avoid conflicts or issues.
Error: Externally-Managed-Environment Solved
Error: externally-managed-environment occurs when a package manager is managing a Python environment, which prevents direct use of pip. It can be solved using a virtual environment:
python3 -m venv ~/py_envs
source ~/py_envs/bin/activate
python3 -m pip install xyz
I encountered this issue when I upgraded my Python version from 3.10 to 3.12.
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to
install.
If you wish to install a Python library that isn't in Homebrew,
use a virtual environment:
python3 -m venv path/to/venv
source path/to/venv/bin/activate
python3 -m pip install xyz
If you wish to install a Python application that isn't in Homebrew,
it may be easiest to use 'pipx install xyz', which will manage a
virtual environment for you. You can install pipx with
brew install pipx
...
2 Ways to Solve “error: externally-managed-environment” in Pip
1. Use a Virtual Environment
One way to solve error: externally-managed-environment is to create a virtual environment folder in your root path. By creating and using a virtual environment, you bypass the system Python entirely, allowing you to install and manage packages freely without impacting the system-wide Python installation.
python3 -m venv ~/py_envs
source ~/py_envs/bin/activate
python3 -m pip install xyz
2. Force Install
The second option is to do a force install. Using --break-system-packages bypasses this protection, allowing you to install the package directly into the system-wide Python environment.
To do so, add --break-system-packages at the end of pip, for example:
pip install xyz --break-system-packages.Frequently Asked Questions
What is an externally-managed-environment error in Python?
The error: externally-managed environment is thrown in Python when a package manager is managing a Python environment, preventing pip from conducting system-wide installations or use.
How do you fix an externally-managed-environment error in pip?
In pip, error: externally-managed environment can be fixed in two ways.
The first option is to use a virtual environment:
python3 -m venv ~/py_envs
source ~/py_envs/bin/activate
python3 -m pip install xyz
The second option is to force install using break-system-packages:
pip install xyz --break-system-packages.What’s the difference between using a virtual environment and the --break-system-packages parameter?
A virtual environment is the safest method for fixing error: externally-managed environment in pip; it creates an isolated space for your project, keeping system Python packages clean.
The --break-system-packages parameter forces pip to install packages directly into the system environment, which is faster but carries the risk of causing version conflicts with OS-level software.
Can I use pipx to fix “error: externally-managed-environment” in pip?
Yes, pipx can be used to solve error: externally-managed environment in pip.
For Python-based applications that can be used globally, the error message may recommend pipx. It automatically handles virtual environments for you, allowing you to run the application globally without interfering with the system-wide Python environment.
