Pip Install Python Packages
How to correctly use 'pip install' on Mac. Common errors with Pip. Comparing Pip, Pipx and alternatives.
Pip is the standard package manager for Python. This guide explains how to use Pip to install software libraries for programming projects. I also suggest alternatives that are more appropriate for running standalone programs or easier for programming.
Before you get started
You'll need a terminal application to use Pip or Python. Apple includes the Mac terminal but I prefer Warp Terminal. Warp increases developer productivity, helping you remember easily-forgotten commands and adds AI troubleshooting. Download Warp Terminal now; it's FREE and worth a try.
Python packages
Python packages can be either software libraries or standalone programs. For example, the requests package is a library that simplifies making HTTP requests, and the cowsay package is a standalone program that displays a cow saying a message. You'll need to add packages to your Python environment if you are a programmer developing Python applications or if you are a user installing programs that require Python.
Pip
Pip is a long-time and popular choice for installing Python packages. Experienced Python developers assume beginners understand the limitations and workarounds required to use pip. However, Pip is not always an appropriate choice or the best choice.
Pip's dependency conflict problem
When you run pip install <package>, the package is installed "globally" by default. This means that the package is added to a global Python site-packages directory, which can lead to conflicts if different projects require different versions of the same package. For example, if Project A requires package==1.0 and Project B requires package==2.0, installing both packages globally can lead to conflicts and dependency hell. Without proper isolation, installing one project's dependencies can break another's.
Recent versions of pip implement PEP 668 to prevent attempts to install packages globally, resulting in the message error: externally-managed-environment.
Pipx for applications
Before you run Pip for the first time, ask yourself if you are installing a Python application. If you are installing a Python application, not installing a software library for a programming project, you should install Pipx and use Pipx.
Pipx is ideal for standalone applications and Python-based tools and utilities that are meant to be accessed from the command line across multiple projects. Use pipx install for Python-based tools and utilities that need to be available system-wide but isolated from each other. Examples include standalone applications such as Youtube-dl and Python coding tools such as Ruff. Without Pipx, Python prevents global package installation, blocking with error: externally-managed-environment or creating a duplicate "shadow" Python installation. Pipx works like the Homebrew software package manager but for Python-based command-line tools, with easy uninstallation that leaves the global environment clean, and installs applications in isolated environments, so they don't interfere with each other. See our guide:
If you are following a tutorial or README to install a Python standalone program or utility, you should be able to install Pipx and directly substitute pipx install for pip install, avoiding error messages and dependency conflicts.
Pip and alternatives for programming
If you are installing a Python software library for a programming project, Pip is appropriate but should not be used without a “virtual environment.” Use a Python environment manager such as Venv to create and activate a virtual environment before using Pip. You'll avoid dependency conflicts when you have multiple projects that require different versions of the same packages (dependency hell).
The need for a virtual environment isn't obvious in the early stages of learning Python. It's only after discovering conflicts between Python applications that the value of isolation becomes clear. If you are coming to Python from other software languages, you won't have encountered virtual environments because package managers for other languages isolate projects within folders and often provide options to install packages locally (within a single project) as well as globally (system-wide for all projects). By isolating dependencies in folders, development tools for most other popular languages adopt a project-based approach to package management (for example, Rust's cargo, Ruby's bundler, and JavaScript's npm). If you've used Node to run JavaScript, pip is similar to npm, the Node package manager. However, npm install installs packages within a project by default, whereas pip install installs packages into a system Python or shared Python versions, creating potential conflicts.
The Python ecosystem offers many alternatives for managing project dependencies. Alternatives to Pip include Rye, Pipenv, Conda, and Poetry. Alternatives provide more robust dependency management, platform independence, and a better integrated workflow for Python package management. The blog post Python Has Too Many Package Managers provides a good overview.
Rye as an alternative
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. Use Rye when working on Python projects requiring specific versions of libraries. 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 use Rye, you won't need pip, venv, or virtualenv for package installation and environment management. See our guide:
If you are working on a Python project and need to install packages, after installation of Rye, use the command rye init to create a pyproject.toml file in your project root directory. Then use rye add instead of pip install to install Python packages. See our guide Use Rye.
Pip using virtual environments
There are two Python tools for creating virtual environments and using different versions of packages. Venv is a built-in Python package. Virtualenv is a more powerful tool with additional features. These tools allow pip to install Python packages into a virtual environment with its own installation directories, that doesn’t share libraries with other virtual environments. Pip must be used in combination with either Venv or Virtualenv if you want to successfully install packages.
A recent addition to Python, the PEP 668 safety mechanism, makes it difficult to simply run pip install to install a package (a nuance often overlooked in READMEs or tutorials). When you attempt to install a package, you will see the error: externally-managed-environment that results from violating PEP 668 (see error: externally-managed-environment). The error message explains you must create a virtual environment to install packages.
See our guide to install Pyenv and use Pip to see an example of how to use Pip with a virtual environment.
Common errors
New Python developers often encounter these errors when following a README or tutorial that starts with pip install <package>:
Check the links above if you encounter these errors. The zsh: command not found: pip error won’t appear if you've installed Python and correctly set the Mac Python 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.