How to Set Up the PATH Variable for Python on macOS: A Detailed Guide

Introduction / Why This Is Needed

If you see command not found when trying to run Python in the macOS Terminal, most likely the path to the interpreter is not added to the PATH environment variable. In this guide, you'll learn how to properly set up PATH for Python on macOS so that the python and python3 commands work from anywhere in the Terminal.

Prerequisites / Preparation

Before you begin, make sure that:

• You have Python 3.x installed (you can check with python3 --version).
• You are familiar with basic Terminal commands.
• You have access to your home directory to edit configuration files.

Step-by-Step Instructions

Step 1: Check Your Current PATH and Python Location

Open Terminal and run:

echo $PATH

This command will output the current list of paths, separated by colons. Then check where the Python executable is located:

which python3

If the which command outputs nothing, Python is either not installed or its path is not in your PATH. In that case, install Python first (for example, via Homebrew or from the official website).

Step 2: Identify Your Shell and Configuration File

macOS uses different command-line shells: bash (up to Catalina) or zsh (from Catalina onward). Determine your current shell:

echo $SHELL

The output will be something like /bin/zsh or /bin/bash. The corresponding configuration files are:

• For zsh: ~/.zshrc
• For bash: ~/.bash_profile or ~/.bashrc

Open the appropriate file in a text editor. For example, for zsh:

nano ~/.zshrc

Or use vim or any other editor of your choice.

Step 3: Add the Python Path to the PATH Variable

In the opened file, go to the end and add a line that prepends the directory containing the Python executable to PATH. Assuming which python3 returned /usr/local/bin/python3, the directory is /usr/local/bin. Add:

export PATH="/usr/local/bin:$PATH"

💡 Tip: Specify the path to the directory, not the python3 file itself. And use double quotes if the path contains spaces (usually it doesn't).

Save the file and exit the editor. In nano, that's Ctrl+O (Enter to confirm) and Ctrl+X.

Step 4: Apply Changes and Verify

To apply the changes without restarting the terminal, run:

source ~/.zshrc   # for zsh
# or
source ~/.bash_profile   # for bash

If you're not sure which file you edited, simply close and reopen Terminal. Then check that Python is now in your PATH:

which python3

This command should output the path you added (for example, /usr/local/bin/python3). Also check the version:

python3 --version

If the commands work, setup is complete.

Verification

Make sure python3 is available from any directory. Try navigating to another directory, for example:

cd ~
python3 --version

If you see the Python version, PATH is set up correctly. You can also try running Python interactively: python3 and exit with exit().

Potential Issues

Python Not Found After Setup

• Make sure you added the correct path to the directory (not the file itself). Verify that which python3 returns the path you specified in export.
• Ensure you edited the configuration file for your current shell.
• After editing the file, you must run source or restart the terminal.

The Wrong Python Version Runs

The order of paths in PATH matters: the system searches for executables from left to right. If you have multiple Python versions, make sure the path to the desired version comes before others. You can check the order with: echo $PATH.

Error When Running source

There might be a syntax error in the configuration file. Open the file and check that the export PATH="..." line is written correctly, without extra characters.

Changes Don't Persist After Restart

Make sure you edited the correct file (for example, ~/.zshrc for zsh). If you use a different shell, the changes won't apply.