How to Install Python on Mac, Upgrade It & Use VENV (2026)

If you’ve tried to pip install something on a Mac recently, you’ve hit the externally-managed-environment error. Since Python 3.12, Homebrew follows PEP 668, which means virtual environments are no longer optional. They’re mandatory. This guide walks you through how to install Python on Mac using Homebrew, configure your PATH so python works, upgrade between versions without breaking things, and set up venv properly for your projects.

Before you begin: prerequisites

Check your macOS version and architecture (Apple Silicon vs Intel)

Homebrew installs to different locations depending on your Mac’s processor:

Check which you have:

uname -m

• arm64 → Apple Silicon
• x86_64 → Intel

If you want a better terminal experience before diving in, consider setting up a modern Mac development terminal first.

Install Xcode Command Line Tools

macOS ships with its own Python 3 (installed via Xcode Command Line Tools, typically 3.9.x). You need the CLT for Homebrew to work, but do not remove the system Python. macOS tools depend on it.

xcode-select --install

Click “Install” in the dialog. This takes a few minutes.

Verify it installed:

xcode-select -p

Expected output: /Library/Developer/CommandLineTools

Install Homebrew on Mac

Homebrew is the package manager that makes Python installation simple. If you don’t have it yet:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

On Apple Silicon, Homebrew adds its PATH entry to ~/.zprofile automatically. Follow the post-install instructions shown in the terminal. You may need to run:

eval "$(/opt/homebrew/bin/brew shellenv)"

Verify Homebrew is healthy:

brew doctor

Expected: Your system is ready to brew.

If you’re customizing your shell, supercharge your Zsh terminal with useful plugins and enable syntax highlighting in Zsh for a better experience.

Install latest Python on Mac with Homebrew

With Homebrew ready, install the latest stable Python:

brew install python

This installs Python 3.14.x (the current stable release as of 2026), along with pip, setuptools, and wheel.

Verify your Python installation

Run these checks to confirm everything is working:

python3 --version
which python3
which pip3

Expected output:

Python 3.14.6
/opt/homebrew/bin/python3
/opt/homebrew/bin/pip3

Configure your PATH for Python on Mac

Here’s the thing nobody tells you: after brew install python, the command python3 works, but python does NOT. You’ll get:

zsh: command not found: python

Homebrew installs the unversioned symlinks (python, pip) to a separate directory that’s not on your PATH by default. Fix it:

# Add Homebrew Python's unversioned commands to PATH
echo 'export PATH="$(brew --prefix python)/libexec/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Verify:

python --version

Should show the same version as python3 --version.

Install a specific Python version on Mac

Sometimes a project requires a specific Python version. Homebrew provides versioned formulae for this.

How to search for available Python versions in Homebrew

brew search python@

You’ll see entries like [email protected] through [email protected]. For the live, up-to-date list with exact version numbers:

Install the version you need. For example, Python 3.13:

brew install [email protected]

The versioned command works immediately after install:

python3.13 --version

Python 3.13.14

No linking required. You can use python3.13 directly in your commands and virtual environments.

Linking keg-only Python formulae

Versioned Python formulae (like [email protected]) are “keg-only.” Homebrew does not symlink them into your PATH by default. If you try to brew link one and another Python version is already linked, you’ll get an error:

Error: Cannot link [email protected]

If you actually need python3 to point to a different version:

# Unlink the current version first
brew unlink python

# Link the version you want
brew link --force [email protected]

Upgrade Python to the latest version on Mac

This is where most guides get it wrong, including the previous version of this article.

The truth about brew upgrade python (major vs patch upgrades)

brew upgrade python does not jump between major versions. It upgrades to the latest patch of whatever formula you have installed.

# Update Homebrew's package index
brew update

# Upgrade to latest patch of current formula (e.g., 3.14.5 to 3.14.6)
brew upgrade python

Verify:

python3 --version

To jump from one major version to another:

# Install the new major version
brew install [email protected]

# Use it with the versioned command
python3.14 --version

Pin Python to prevent accidental upgrades

When Homebrew upgrades other packages, it can sometimes upgrade Python as a dependency. This changes the Python binary path, which breaks existing virtual environments. Pin your Python version to prevent this:

# Pin prevents accidental upgrades
brew pin [email protected]

# Check what's pinned
brew list --pinned

# Unpin when you're ready to upgrade
brew unpin [email protected]

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Understanding PEP 668: why you need virtual environments

This is the section I wish existed when I first ran into the error. If you’ve tried to install a Python package globally with pip and gotten a wall of red text, here’s why.

The externally-managed-environment error explained

Starting with Python 3.12, Homebrew marks its Python installation as “externally managed” (per PEP 668). This means:

pip install requests

Results in:

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.

This is not a bug. It’s a deliberate protection. Homebrew Python is managed by Homebrew. Letting pip install packages globally could conflict with Homebrew-managed packages and break your system.

The fix: use a virtual environment (for project dependencies) or pipx (for CLI tools). Both are covered in the next sections.

Reference: Homebrew and Python documentation.

Run Python in VENV on Mac

Virtual environments are now the standard (and required) way to manage Python project dependencies. Here’s the full workflow.

Create a Python virtual environment on Mac

Navigate to your project directory and create a venv:

cd ~/my-project
python3 -m venv .venv

Activate and use your virtual environment

source .venv/bin/activate

Your terminal prompt changes to show the active environment:

(.venv) user@mac my-project %

Verify it’s working:

which python

Should show: /Users/youruser/my-project/.venv/bin/python

Now pip install works without PEP 668 errors:

pip install requests

Install packages and freeze requirements

This is the practical workflow that was missing from the old article:

# Install packages inside your active venv
pip install requests pandas fastapi

# Freeze current dependencies to a file
pip freeze > requirements.txt

The requirements.txt file lets anyone recreate the same environment:

# On another machine (or after cloning a repo):
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

uv pip install requests pandas
uv pip freeze > requirements.txt
uv venv  # creates venvs faster than python -m venv

Deactivate the virtual environment

When you’re done working:

deactivate

Your prompt returns to normal. The packages stay installed in .venv/. Nothing is lost.

Add .venv to .gitignore

Never commit your virtual environment to git. Add these entries to your .gitignore:

.venv/
venv/
env/

Troubleshooting common Python on Mac issues

echo 'export PATH="$(brew --prefix python)/libexec/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
python --version

# Just use the versioned command. No linking needed.
python3.13 --version
python3.13 -m venv .venv

brew unlink python
brew link --force [email protected]

python3 -m venv .venv
source .venv/bin/activate
pip install <package>

brew install pipx
pipx ensurepath
pipx install black

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Alternatives to consider

Homebrew is the simplest path, but it’s not the only one. Here are the main alternatives.

uv: a modern Python package manager

uv by Astral is an all-in-one Python tool that replaces pip, venv, pyenv, and pipx. It’s written in Rust and significantly faster than pip.

brew install uv
uv venv           # create venvs faster
uv pip install requests  # drop-in pip replacement
uv python install 3.13   # install specific Python versions

If you want a single tool that handles everything covered in this article, uv is worth a look. Full guide: uv, a modern Python package manager. For deployment: deploy a Python project with uv and Dokploy.

pyenv: manage multiple Python versions

pyenv is for when you need to switch between Python versions frequently across different projects. Homebrew’s own docs recommend it “if you require stability of minor or patch versions for virtual environments.”

brew install pyenv
pyenv install 3.13.14
pyenv install 3.14.6
pyenv global 3.14.6

pyenv manages versions independently of Homebrew, so upgrading Homebrew won’t accidentally change your project’s Python version. More overhead to set up, but more control.

Official Python.org installers

Python.org provides macOS universal2 installers that work on both Apple Silicon and Intel. These are standalone, no Homebrew dependency.

Use this if you don’t want Homebrew at all, or if you need a specific Python build. The downside: manual PATH setup, no automatic updates, and it doesn’t integrate with the Homebrew ecosystem.

pipx: install Python CLI tools globally

pipx installs Python CLI tools (like black, ruff, mypy, poetry) in isolated environments, making them available globally without polluting your system Python.

brew install pipx
pipx ensurepath
pipx install black
pipx install ruff

Next steps: what to build with Python on Mac

Now that you have Python installed and know how to manage environments, here’s where to go from here:

• Explore the best Python web frameworks: find the right framework for your next project
• Build a UI for your Python app with NiceGUI: quick-start guide for Python UI apps
• Add multiple pages to your NiceGUI app: follow-up for NiceGUI projects
• Run your Python app in Docker: containerize your project for consistent deployments
• Deploy a Python project with uv and Dokploy: production deployment on a VPS
• Generate AI images locally with Python: run Flux models on your Mac

If you’re deploying to a server, Hetzner offers affordable EU VPS that works well for Python apps.