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.

How you fix the Mac $PATH depends on how you have installed Python. This guide introduces the Mac $PATH configuration setting and shows how to set it correctly for various Python installation scenarios.

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. There's two possible reasons for this error: Python is not installed or the Mac $PATH is not set correctly.

I've written a guide to troubleshooting this error:

zsh: command not found: python if Python is not installed or the Mac PATH is not set correctly

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.

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 Terminal. The shell (by default, Zsh, the Z shell) is the program that runs in the Mac Terminal that interprets Unix commands. Shell settings, or environment variables, are stored in configuration files and set when you login or launch the 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 programs you install. 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's 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 one 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's an easy way to install many useful software programs for the terminal, or command line. On Apple silicon (M1, M2, and M2 CPUs), 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 belongs 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 the Mac Terminal:

$ 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, maOS 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 with Apple M1, M2, M3 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 in the Terminal until you've quit and restarted the terminal. 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.

Python installed with the official installer

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

Though it's 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.

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

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

This command will list any the versions of Python installed with the official installer. If Python is not there, it was not installed with the official installer. If it's 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's best to reinstall Python with Homebrew, Pyenv, or Rye (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
[email protected]

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 Rye, the all-in-one 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
==> [email protected]: 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. However, 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 in the Terminal until you've quit and restarted the terminal.

Your Mac $PATH should contain the Python executable directory:

$ echo $PATH
/opt/homebrew/opt/[email protected]/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

Note that I recommend to install Python with Rye instead of Pyenv as a Python version manager. Rye 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 in the Terminal until you've quit and restarted the terminal.

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

Python installed with Rye

If Python was installed with Rye, you can list installed Python versions:

$ rye --version
rye 0.32.0
$ rye toolchain list
[email protected] (/Users/username/.rye/py/[email protected]/bin/python3)

Your Mac $PATH should contain the Rye shims directory:

$ echo $PATH
/Users/username/.rye/shims:...

If you need to fix the Mac $PATH, don't add the Python executable path directly. Instead, add the Rye shims directory to the Mac $PATH using the Rye ~/.rye/env script. Add this command as the last line of your ~/.zprofile file to configure the Z shell for Rye.

source "$HOME/.rye/env"

When your terminal session starts, Z shell will run the ~/.rye/env script to set shims to intercept and redirect any Python commands. You'll need double quotes because the command contains spaces or special characters. Rye adds the shims to your $PATH so that running the command python or python3 will run a Rye-installed Python version.

Changes to the ~/.zprofile file will not take effect in the Terminal until you've quit and restarted the terminal.

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:

fixing zsh: command not found: python
an introduction to Mac PATH
an introduction to shell configuration

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.