Error: externally-managed-environment
How to fix 'error: externally-managed-environment' on Mac. An error installing Python packages using Pip, the Python package manager.
This is the error you'll see:
$ pip install <package>
error: externally-managed-environment
If you see this error, you're trying to install a Python software library (a "package") using Pip, the default Python package manager. Recent versions of Pip implement PEP 668 to encourage the use of virtual environments and reduce dependency conflicts (dependency hell).
Before you get started
You'll need a terminal application to fix the error. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.
How to fix "Error: externally-managed-environment"
There are several approaches to resolve this error, depending on what you are trying to achieve and your comfort with Python and virtual environments.
Python packages can either be standalone applications and tools or, more commonly, reusable software libraries that add pre-built capabilities to your Python code.
Applications and tools
If you wish to install and run a standalone application such as Youtube-dl or a Python coding tool such as Ruff, you should install and use Pipx. Pipx creates isolated environments for tools and utilities, ensuring that dependencies are introduced without affecting global site packages or other projects. Pipx simplifies the management and upgrade of Python tools, much like the Homebrew software package manager but for Python-based command-line tools, with easy uninstallation that leaves the global environment clean. If you intend to run standalone applications or Python coding tool, use pipx install instead of pip install. See our guide:
To install standalone applications and tools, use pipx install <package> instead of pip install <package> after installing Pipx. You won't encounter the PEP 668 "externally-managed-environment" error when using Pipx.
Programming using Python libraries with Rye
Python is popular because of many software libraries (“packages”) offered through the Python Package Index (PyPI). Any software project is a hierarchy of packages that provide basic functionality, alongside custom code that adds unique features for the specific application. You'll need a package manager to install, update, and remove software packages.
If you are new to Python, or you want to streamline your Python development workflow, you should use Rye. Rye is a new all-in-one tool for Python version and package management. Rye is suitable for installing project-specific software libraries that shouldn't be installed globally. Rye prevents conflicts by isolating each project's environment and dependencies, using a project configuration file that's similar to the folder-based approach of other programming languages. I recommend using Rye as it simplifies Python development by focusing on managing projects without multiple tools.
If you are working on a Python programming project, use rye add instead of pip install to install Python packages. See our guide:
You won't encounter the PEP 668 "externally-managed-environment" error when using Rye.
Programming using Python libraries with Pip and Venv
Experienced Python developers may prefer to use the built-in Python package manager, Pip, and the built-in Python virtual environment tool, Venv. Pip and Venv are part of the Python standard library, so they are always available when you install Python. Pip and Venv are suitable for managing Python software libraries that are shared across multiple projects.
If you're working on a Python project that uses software libraries, you must use a virtual environment to manage dependencies. A virtual environment is a self-contained directory that contains a Python installation and a copy of the Python standard library. You can install packages into the virtual environment without affecting the global Python installation or other projects. This isolation ensures that your project's dependencies are consistent and won't conflict with other projects.
To install Python packages for a project with pip, you first must use Venv or Virtualenv to create and activate a virtual environment to avoid dependency conflicts.
You can create a virtual environment with python -m venv venv and activate it with source venv/bin/activate. Then you can install Python packages with python -m pip install <package>.
Don't use pip install to install Python packages. Instead, use python -m pip install <package>. By prefacing the pip command with python -m, you use the version of Pip that comes with the Python interpreter you are using. This ensures that the package is installed in the correct Python environment.
Prefacing the pip command with python -m, avoids a "shadowed" pip where the pip command accesses a different version of pip than intended, due to system path configurations or virtual environments. This minimizes unexpected behavior or errors when installing packages.
If you use Rye, you won't need pip, venv, or virtualenv for package installation and environment management.
Other common errors
For the error:
$ python ...
zsh: command not found: python
See our guide command not found: python.
For the error:
$ pip install <package>
zsh: command not found: pip
See our guide command not found: pip.
You'll see these errors if Python or Pip is not installed or not in the Mac PATH.
What's next
My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.