Python

Written & tested for accuracy by a developer (not AI)

Mac Python PATH

Find the Python PATH on Mac. How to add Python to Mac PATH. Set the Mac PATH for Python. Fix errors with the Mac PATH environment variable for Python.

If you want to use Python on a Mac, you'll need to set the Mac $PATH. Setting the Mac $PATH means using a text editor to change shell configuration files. For beginners, this process should be exciting rather than daunting, as it provides a chance to explore the hidden capabilities of a Mac.

The PATH is an environment variable that controls where the operating system looks for executables. Setting the Mac PATH for Python is crucial because macOS may have multiple Python versions installed. Your PATH determines which version runs when you type python or python3. It is important to understand and check the PATH for troubleshooting.

How you set the Mac $PATH depends on how you have installed Python. This guide shows how to set it correctly for popular Python installation scenarios.

Setting the Mac PATH is one step in setting up your Mac for development. See the guide to set up a Mac for development.

Before you get started

You'll need a terminal application to set the $PATH. 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.

The error from a missing Python or incorrect PATH

If the Mac $PATH is incorrect, this is the error you'll see when you try to run Python from the terminal:

$ python ...
zsh: command not found: python

You'll see zsh: command not found: python because you are trying to run the Python interpreter in the terminal. The error message shows that the Zsh shell ("the command line interpreter") cannot find the Python command. You can get the correct python command when you use a Python virtual environment, or when you install Python with uv or pyenv. The Mac $PATH determines which Python installation will run.

I've written a guide to troubleshooting this error:

You might already have Python because developers commonly install Xcode Command Line Tools. When you install Xcode Command Line Tools, Apple includes Python 3.9.6. That's the older system version and you should install a newer Python version.

If you're sure that Python is installed and you believe the Mac $PATH is not set correctly, continue with this guide. First, I describe the Mac $PATH and explain how to set it. Then I provide step-by-step instructions for setting the Mac $PATH for each likely Python location.

Differences between python and python3

Before setting the $PATH, it helps to know why two similar Python commands exist.

Python 2 reached end of life in 2020. By now, every current Python should be Python version 3 and python and python3 will both run the same language interpreter. The reason python is missing is historical: when Python 2 and Python 3 were both in use, the python command usually meant Python 2, so people entered python3 to prevent running the older version. PEP 394, the standard that governs this, still permits a distributor to "not provide python command" at all.

Unfortunately, the naming collision is still a source of confusion and requires workarounds if you want to just enter python and get what you want.

Here is what you actually get on a Mac:

  • Apple's system Python (from Xcode Command Line Tools) installs /usr/bin/python3 only. There is no python command and Apple does not provide one.
  • Homebrew puts python3 in its bin directory but not python. It does create an unversioned python, in a separate libexec/bin directory that is not on your $PATH. Adding that directory to the $PATH is what makes python work. See Install Python with Homebrew.
  • The official python.org installer places python3, plus version-numbered commands such as python3.14, in /usr/local/bin. It installs no unversioned python. See Download Python for Mac.
  • Pyenv creates "shims" for every command a Python version provides, including python. Both commands work once pyenv init is in your shell configuration.
  • The uv utility installs python and python3 together in ~/.local/bin. Both commands work with no extra setup.

Most developers want to type python. If your installation method does not provide it, setting the $PATH is the fix, and that is what the rest of this guide covers.

There is one exception. Apple's system Python can never provide a python command, because nothing is added to the $PATH that would supply one. If you only want to run an occasional script with the system Python, you can create a shell alias instead. See Alias python3 to python.

What is the Mac $PATH?

The Mac $PATH is a list of directories (folders) where the computer's commands and programs are stored for use by the command line, or a terminal application. The shell (by default, Zsh, the Z shell) is the program that runs in a terminal application that interprets Unix commands. Shell settings, or environment variables, are stored in configuration files and set when you login or launch a terminal application. The $PATH variable enables the system to locate the necessary programs without needing the full path for execution.

In this guide, I'll show how to set the $PATH environment variable so you can run Python. For a full explanation about Zsh and setting environment variables, see Shell Configuration.

If you don't set the $PATH

If you don't set the $PATH environment variable, you will encounter these problems:

  • Errors such as "Command not found"
  • Programs that fail with dependency issues
  • Increased manual effort

Explained in detail:

  • If you don't set the Mac $PATH, the shell won't be able to locate executable files or commands, particularly programs you've added that are not basic shell commands.
  • Many applications and scripts rely on the $PATH variable to find necessary tools or executables. Without a properly set $PATH, these applications will fail.
  • If you don't set the Mac $PATH, you'll need to specify the full path to an executable every time. This can be tedious and annoying, especially for commands you use frequently.

How the $PATH works

The $PATH environment variable determines the directories the shell searches for executable files. It is a list of directory paths, separated by colons (:). For example, a default $PATH looks like /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin.

If you install a new program for use from the command line, you may need to add to the $PATH environment variable. For example, if you install a new program cowsay in the /usr/local/bin directory, $PATH must include the directory or else you'll need to type /usr/local/bin/cowsay every time you want to run the program. Remember you may not be the only entity trying to run the cowsay program: If the cowsay program is called by another program and the $PATH is not set, it won't be found and the program will fail.

Consider the Homebrew package manager for macOS. It is one of the first tools you'll need for a local development environment for programming on a Mac. It is an easy way to install many useful software programs for the terminal, or command line. On Apple Silicon (M-series), Homebrew installs files into the /opt/homebrew/ folder, which is not part of the default shell $PATH. After you Install Homebrew, you must set the shell $PATH to use any software programs installed by Homebrew.

Where to set the $PATH

Set the $PATH environment variable in the ~/.zprofile (Zsh Profile) file. The tilde ~/ is a Unix abbreviation for your home directory. That is, the .zprofile file can be found in your home directory.

These are the two zsh shell initialization files that are commonly used for configuration:

  • ~/.zshrc (Zsh Run Control): This file is best for adjusting the appearance and behavior of the shell, such as setting command aliases and adjusting the shell prompt.
  • ~/.zprofile (Zsh Profile): This file is ideal for commands that should be executed only when the terminal window is opened, such as setting the $PATH environment variable.

The article .zshrc or .zprofile explains the differences.

By default, the ~/.zprofile configuration file does not exist for a user on a new Mac. You'll need to manually create the file in your home directory to properly configure your development environment.

You can create a new file from the command line with the touch command:

$ touch ~/.zprofile

After you create the file, you can edit it.

How to set the $PATH

You can use TextEdit, the default macOS graphical text editor, to edit the shell configuration files. You can open a file in TextEdit from a terminal application:

$ open -e ~/.zprofile

You also can use the command line editors nano or vim to edit the shell configuration files. See Shell Configuration for more about editing shell configuration files.

Decoding the default Mac $PATH

The default $PATH includes the contents of /etc/paths and all the files in the /etc/paths.d directory. On login, macOS uses a utility /usr/libexec/path_helper to set the default $PATH environment variable from the contents of the /etc/paths file and all the files in the /etc/paths.d directory. The path_helper utility is executed at login from /etc/zprofile. It does not duplicate paths, and just appends additional unique values to any existing path.

On old Macs (macOS Mavericks and earlier), the default $PATH was:

  • /usr/bin:/bin:/usr/sbin:/sbin.

For macOS El Capitan, Sierra, High Sierra, Mojave, and Catalina, the default $PATH was:

  • /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin.

On macOS Ventura and newer, the default $PATH contains Apple's cryptexes, a system for applying security patches.

  • /usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:... (and more, too long to show here).

Directories named bin are for "binaries" or executable command line programs. The sbin directories are for system management programs. The bin and /usr/bin directories are for basic command line programs provided by Apple. The /usr/local/bin is for user-installed executables.

Add to the $PATH

To edit the Mac $PATH, use a text editor to edit the ~/.zprofile file. The export command sets environment variables in the zsh shell. Here's the format for setting the $PATH:

export PATH=/path/to/directory:$PATH

The new $PATH variable will be exported to the environment as a combination of the previous $PATH plus a new directory. The new directory comes first; it will take precedence over any directories present in the previous $PATH. A : colon character separates the new directory path from the existing directories in the previous $PATH.

Here's an example of adding the Homebrew directory used on Apple Silicon (M-series) computers:

export PATH=/opt/homebrew/bin:$PATH

You might see this form with double quotes: export PATH="/opt/homebrew/bin:$PATH" but you won't need the double quotes unless a directory name contains spaces or special characters.

This example differs from what Homebrew recommends. Homebrew provides its own shellenv utility for setting its path in the ~/.zprofile file. See the article Install Homebrew for details. Here's what a Homebrew $PATH setting looks like:

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

Reset the shell session

Changes to the ~/.zprofile file will not take effect until you quit and reopen your terminal application. Alternatively (this is easier), you can use the source command to reset the shell environment:

$ source ~/.zprofile  # Or just restart your terminal

The source command reads and executes a shell script file, in this case resetting the shell environment with your new $PATH setting.

Fix the Mac PATH for Python

Before you can fix the Mac $PATH setting, you need to determine how Python was installed and where it is located. Here you'll find the most popular ways to install Python and a fix for the PATH for each.

Python installed with the official installer

Did you install Python with the official installer from the Python website?

Though it is the official Python website installer, most Python developers avoid using it because it clutters a Mac in ways that are difficult to manage. The installer package from the Python website adds symlink files to /usr/local/bin, modifies your Mac PATH, and installs the latest Python version in the macOS /Library/Frameworks folder. Developers don't like this because the installer makes system-wide changes that are difficult to reverse and break existing projects when macOS updates occur.

Check the contents of the Python installation in the macOS Frameworks directory:

$ ls -l /Library/Frameworks/Python.framework

This command will list any of the versions of Python installed with the official installer. If Python is not there, it was not installed with the official installer. If it is there, the official installer should have set the Mac $PATH correctly and set symbolic links in /usr/local/bin to the Python executable. If it was not set up correctly, it is best to reinstall Python with Homebrew, Pyenv, or UV (see update Python).

If you decide to use Python with the official installer, your PATH should look like this:

$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:...

The directory /usr/local/bin should be the leftmost element, taking precedence over other directories. After editing the shell configuration file, be sure to restart your terminal or execute the source command.

Python installed with Homebrew

You can check if python was installed with Homebrew. It will be listed among the Homebrew-installed packages:

$ brew list | grep python
python@3.12

This will show a Python version if it is installed via Homebrew. If you see zsh: command not found: brew, you don't have Homebrew. You may want to install Homebrew for your projects. If you don't want Homebrew, you can install Python with UV, a unified tool for managing Python projects.

If Homebrew shows Python is installed, you can get more information about the Python version, including its installation path:

$ brew info python
==> python@3.12: stable 3.12.3 (bottled)
.
.
.

This command will give you a summary that includes the version of Python installed via Homebrew and the path to the executable.

Installing Python with brew install python doesn't set the Mac $PATH. You can add the Homebrew Python executable path directly to the Mac $PATH in the .zprofile file. Alternatively, Homebrew recommends modifying the ~/.zprofile file by adding the following line as the last line in the ~/.zprofile file:

export PATH="$(brew --prefix python)/libexec/bin:$PATH"

Changes to the ~/.zprofile file will not take effect until you quit and reopen your terminal application.

Your Mac $PATH should contain the Python executable directory:

$ echo $PATH
/opt/homebrew/opt/python@3.12/libexec/bin:...

Entering python --version should now display the Python version number. This solves the error zsh: command not found: python.

Python installed with Pyenv

Pyenv is a popular Python version manager for installing multiple Python versions and switching between them. It is typically installed with Homebrew. If you have Homebrew installed, you can check if Pyenv is installed:

$ brew list | grep pyenv
pyenv

You may have Pyenv, but I recommend to install Python with UV instead of Pyenv as a Python version manager. UV is an all-in-one tool that provides a streamlined solution for Python development.

You can verify that Pyenv is installed by running:

$ pyenv --version
pyenv 2.4.0

If Pyenv is installed, you can list all Python versions installed on your system through Pyenv:

$ pyenv versions
* system (set by /Users/username/.pyenv/version)
3.12.2

This command will display a list of all Python versions that have been installed with Pyenv. The currently active Python version (the one being used in your terminal session) is indicated by an asterisk (*). You'll see only system if you haven't installed any Python versions with Pyenv.

Check if a Pyenv global version is set:

$ pyenv global
system

If Pyenv shows a response "system," make sure you've installed a Python version with Pyenv and set it as the global version. Pyenv doesn't set a default Python version the first time you install Python. Instead, it defaults to a system Python (which doesn't exist after macOS 12.3 unless Xcode Command Line Tools is installed).

You can set a Python version as the global version with:

$ pyenv global 3.12

If you've installed a Python version with Pyenv, seen it listed by pyenv versions, and set it as the global version, you'll still need to set the Mac $PATH to eliminate the error zsh: command not found: python.

Edit your ~/.zprofile file to add Python versions installed by Pyenv to the Mac $PATH. Add the following lines:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Changes to the ~/.zprofile file will not take effect until you quit and reopen your terminal application.

Entering python --version should now display the Python version number. This solves the error zsh: command not found: python.

Python installed with UV

UV is the new favorite for installing and managing Python because it offers a single coherent setup and packaging system that's 10-100x faster than previous tools, eliminating the need for separate tools such as pip, pyenv, and venv for managing versions, software libraries, and environments.

Check if UV is installed:

$ uv --version
uv 0.12.0

If you see zsh: command not found: uv you don't have UV. See Install Python with UV or command not found: uv. The UV installer edits a shell startup file automatically to ensure UV and its Python versions are on your PATH, but this behavior can be disabled. It uses the first of ~/.zshrc or ~/.zshenv that already exists, and creates ~/.zshrc if neither does, so on most Macs the line lands in ~/.zshrc. If you set the PATH yourself, use ~/.zprofile (see .zshrc or .zprofile).

If UV is installed, you can list all installed Python versions:

$ uv python list --only-installed

UV provides a command to show the directory that contains the actual Python executables:

$ uv python dir
/Users/username/.local/share/uv/python

Your Mac $PATH should contain the UV Python binaries path:

$ echo $PATH
/Users/username/.local/bin:...

If you've manually added added the UV Python binaries path, it will be leftmost in the PATH list. If the UV installer utility added to the PATH, the UV Python binaries path will be rightmost in the PATH list.

If you need to set the Mac $PATH, add the UV Python binaries directory to your ~/.zprofile file:

export PATH="$HOME/.local/bin:$PATH"

Changes to the ~/.zprofile file will not take effect until you quit and reopen your terminal application.

Entering python --version should now display the Python version number. This solves the error zsh: command not found: python.

More information

I've written other guides that may be helpful:

Uninstall Python

If the real problem is that you have too many Python versions installed, see Uninstall Python on Mac.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.