Python

audience developer
level all
topic Python
subtopic Installation

Install Python Packages

How to install Python packages on Mac. Correct use of 'pip install'. Errors with Pip. Comparing Pip, Pipx, and alternatives.

This guide shows how to install Python packages on a Mac. Pip is the standard package manager for Python. However, there are newer and better package managers for running standalone Python programs or Python programming. Read on for details, but here's a quick summary:

  • For installing Python packages when writing code, use UV.
  • For installing Python stand-alone applications, use Pipx.
  • Use pip install if you must use the older Python approach
  • But to avoid headaches, don't use Pip without virtual environments.

Before you get started

You'll need a terminal application to use 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 is popular because of many software libraries ("packages") offered through the Python Package Index (PyPI). Any software application is a nest of packages for basic functions, combined with custom code that adds unique features. For example, some packages connect to databases or APIs, or make development easier with testing. You'll use a package manager to install, update, and remove software packages. However, most packages depend on other external software libraries so the package manager must fetch and install any dependencies required by a package ("dependency resolution").

When you install Python packages, it's important to understand that they fall into two categories:

  • Libraries used in development projects (like requests for HTTP calls)
  • Standalone applications run from the command line (like Ruff)

Which tool to install Python packages?

Here's a decision tree to pick the right tool for installing Python packages:

Are you installing a command-line application?
├── YES → Use Pipx to install Python application packages
└── NO → Are you working on a coding project?
    ├── YES → Do you want a unified toolset?
    │   ├── YES → Use UV to install Python packages (recommended)
    │   └── NO → You'll use a combination of tools:
    │       └── Pip+Venv: Traditional package installation approach

How to install Python packages for applications

If you're installing standalone Python application packages (not libraries for development), Pipx is the best solution for application installation.

What is Pipx?

Pipx isolates application packages from each other while making them available system-wide, similar to how Homebrew works but specifically for Python command-line tool packages.

When to Use Pipx

  • Installing utility packages like Youtube-dl
  • Installing development tool packages like Ruff
  • Any Python application package you want to run from the command line

How to use Pipx

If you are installing a Python application, not installing a software library for a programming project, you should install Pipx (with an "x") and use it instead of Pip (without an "x").

  1. Install Homebrew: If you don't have Homebrew, Install Homebrew first.
  2. Install Pipx: Open the terminal and run brew install pipx.
  3. Update the Mac PATH: Add the ~/.local/bin folder to your Mac PATH.
  4. Install application packages: pipx install <application-name>

For detailed instructions on installing Python application packages, see the full guide: Install Pipx.

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, if the application was built with "console script entry points."

How to install Python packages for coding

For developing Python projects, UV is better than traditional Pip for installing Python packages. UV is a fast, modern replacement that combines version management, environment management, and Python package installation in a single, unified tool.

  • 10-100x faster than other Python package installation tools
  • Eliminates the need for separate tools (pip, pyenv, venv)
  • Project-focused approach to installing Python packages, similar to other programming languages

How to use UV for installing Python packages

  1. Install UV
  2. Create a new project: uv init
  3. Install Python packages: uv add <package-name>

Other alternatives for installing Python packages

While UV is newer and better, these alternatives have specific strengths when installing Python packages:

  • Poetry: Strong dependency resolution and publishing capabilities when installing Python packages
  • Conda: Popular in scientific computing for installing Python packages with non-Python dependencies
  • Pipenv: Environment and dependency management in one tool for Python package installation

Using Pip for coding

If you must use Pip to install Python packages (for example, when following tutorials), always use it with virtual environments. You'll avoid dependency conflicts when you have multiple projects that require different versions of the same packages (dependency hell).

Dependency files

Python packages often depend on other packages. Managing these dependencies properly is essential to avoid conflicts when installing Python packages.

Pip specifies packages in a requirements.txt file. Newer package managers such as UV use a pyproject.toml file instead. Updating a package with pip may not automatically update all of its relative dependencies which can lead to conflicts.

  • requirements.txt: Traditional Pip dependency file for package installation
  • pyproject.toml: Modern specification used by UV, Poetry, etc. when installing Python packages

Virtual environments

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.

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.

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.

Here's a typical workflow for Pip with Venv:

  1. Create a virtual environment:

    python -m venv .venv
    
  2. Activate the environment:

    source .venv/bin/activate
    
  3. Install Python packages using Pip:

    pip install <package-name>
    
  4. Deactivate when finished installing packages:

    deactivate
    

See my guide to install Pyenv and use Pip to see an example of how to use Pip with a virtual environment.

Common errors with Pip

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. The error: externally-managed-environment shouldn't occur if you use Venv or Virtualenv.

Comparison of Python package installation tools

| Tool | Best For Installing | Dependency File | Virtual Environments | Installation Speed | Learning Curve | |------|----------|----------------|---------------------|-------|---------------| | UV | Development packages | pyproject.toml | Built-in | Very Fast | Low | | Pipx | Application packages | N/A | Built-in | Medium | Very Low | | Pip+Venv | Following tutorials for package installation | requirements.txt | Manual | Slow | Medium | | Conda | Scientific package installations | environment.yml | Built-in | Slow | High |

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.