Introduction

macOS ships with a system Python that should not be modified. Homebrew installs Python to /opt/homebrew/bin/ (Apple Silicon) or /usr/local/bin/ (Intel). To make the Homebrew version the default, add its directory to the front of your PATH in your shell configuration file. This ensures python3 (and optionally python) resolves to the Homebrew version instead of the system one.

Install Python via Homebrew

1brew install [email protected]
2
3# Check what was installed
4brew info [email protected]

Homebrew installs Python to:

• Apple Silicon (M1/M2/M3): /opt/homebrew/bin/python3.12
• Intel Mac: /usr/local/bin/python3.12

It also creates symlinks like python3 and pip3 in the same directory.

Check Current Python Versions

1# Which python3 is active
2which python3
3# Might show: /usr/bin/python3 (system) or /opt/homebrew/bin/python3 (Homebrew)
4
5# Version
6python3 --version
7
8# All Python installations
9where python3
10# /opt/homebrew/bin/python3
11# /usr/bin/python3

Set Homebrew Python as Default

Add the Homebrew bin directory to the front of your PATH.

For zsh (default on macOS Catalina+):

1# Edit ~/.zshrc
2echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
3
4# For Intel Macs:
5# echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
6
7# Reload
8source ~/.zshrc
9
10# Verify
11which python3
12# /opt/homebrew/bin/python3
13python3 --version
14# Python 3.12.x

For bash:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Create a python Alias (Optional)

macOS does not provide python (only python3). To use python as a command:

1# Option 1: Shell alias
2echo 'alias python=python3' >> ~/.zshrc
3echo 'alias pip=pip3' >> ~/.zshrc
4source ~/.zshrc
5
6# Option 2: Symlink
7ln -s /opt/homebrew/bin/python3 /opt/homebrew/bin/python
8ln -s /opt/homebrew/bin/pip3 /opt/homebrew/bin/pip

The alias approach is safer because it does not affect scripts that explicitly call python3.

Managing Multiple Python Versions

Homebrew supports multiple Python versions side by side:

1brew install [email protected]
2brew install [email protected]
3brew install [email protected]
4
5# Each version is available as:
6python3.11 --version
7python3.12 --version
8python3.13 --version
9
10# The unversioned 'python3' points to the latest installed
11python3 --version
12
13# Switch the default by adjusting PATH priority
14export PATH="/opt/homebrew/opt/[email protected]/bin:$PATH"

Using pyenv (Alternative)

For frequent version switching, pyenv is more flexible than Homebrew's Python:

1brew install pyenv
2
3# Add to shell config
4echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
5echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
6echo 'eval "$(pyenv init -)"' >> ~/.zshrc
7source ~/.zshrc
8
9# Install and set a default version
10pyenv install 3.12.2
11pyenv global 3.12.2
12
13python --version
14# Python 3.12.2

pyenv manages versions independently of Homebrew and supports per-project Python versions via .python-version files.

Fixing pip and Virtual Environments

1# Ensure pip uses the Homebrew Python
2which pip3
3# /opt/homebrew/bin/pip3
4
5pip3 --version
6# pip 24.x from /opt/homebrew/lib/python3.12/site-packages/pip
7
8# Create a virtual environment
9python3 -m venv myproject
10source myproject/bin/activate
11
12# Inside the venv, 'python' and 'pip' point to the venv's copies
13which python
14# /path/to/myproject/bin/python

Homebrew Python PATH Details

1# Main binaries
2/opt/homebrew/bin/python3        # Symlink to latest
3/opt/homebrew/bin/python3.12     # Version-specific
4/opt/homebrew/bin/pip3
5
6# Versioned opt directory (for PATH pinning)
7/opt/homebrew/opt/[email protected]/bin/python3.12
8
9# Framework (for tools that need Python.framework)
10/opt/homebrew/opt/[email protected]/Frameworks/Python.framework
11
12# Site packages
13/opt/homebrew/lib/python3.12/site-packages/

Common Pitfalls

• Modifying the system Python: macOS system Python (/usr/bin/python3) is used by system tools. Never modify it, install packages into it globally, or delete it. Always use Homebrew Python or virtual environments for your projects.
• PATH order matters: If /usr/bin appears before /opt/homebrew/bin in PATH, the system Python wins. Ensure the Homebrew path is prepended (at the front), not appended.
• Homebrew Python upgrades breaking virtual environments: brew upgrade python may change the Python minor version (3.11 to 3.12), breaking existing virtual environments that link to the old version. Recreate venvs after major Homebrew Python upgrades.
• Using sudo pip install: Never install Python packages with sudo. It installs into the system Python's site-packages and can break macOS tools. Use pip install --user or a virtual environment.
• Confusing python and python3: macOS intentionally does not provide a python command (PEP 394). Scripts using #!/usr/bin/env python may fail. Use python3 explicitly or create an alias.

Summary

• Install Python with brew install [email protected]
• Add /opt/homebrew/bin to the front of your PATH in ~/.zshrc
• Use python3 (not python) — create an alias if you need the shorter command
• Use pyenv for managing multiple Python versions with per-project switching
• Always use virtual environments for project dependencies
• Never modify or install packages into the macOS system Python