Command not found: python
How to fix command not found: python on Mac. For zsh or bash. You'll see this error when Python is not installed or the Mac $PATH is not set correctly. How to fix the Mac PATH for Python.
New users of Python on macOS often encounter the error zsh: command not found: python. This error occurs when python is not a shell command. The solution is to correctly install Python and set the Mac PATH. But first you need to think about why you are trying to run Python because the solution depends on whether you are running a Python program or developing a Python project. The solution is also complex because the evolving Python ecosystem lacks standardized development tools and Python can be installed in multiple ways.
This is the error you'll see:
$ 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.
If you see an error that begins with bash... you are using the Bash shell.
$ python ...
bash: command not found: python
If you are using the Bash shell, you likely have an older version of the macOS. Check macOS and update macOS and switch to the Zsh shell.
Before you get started
You'll need a terminal application to fix the error. 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.
Are you programming in Python or just running a utility?
Before you try to fix the error zsh: command not found: python, think about why you are trying to use Python. The solution to the error zsh: command not found: python differs depending on whether you are running a stand-alone program or coding a Python project.
If you are just running a program such as a script or utility, and not installing any Python packages, it can be okay to use the system Python installed with Xcode Command Line Tools or the Python version installed with Homebrew, though it's better to install UV or install Pipx. However, if you are writing code, you need to install Python and set up a development environment to isolate dependencies and avoid conflicts by using UV or Pyenv.
For stand-alone Python utilities
Examples of utilities or command-line Python applications are Youtube-dl, a command-line tool to download videos from YouTube, or Ruff, a popular Python code formatter. Utilities should be installed so they are available to all projects ("globally") but isolated from each other.
READMEs and tutorials often say to install Python utilities with pip install. This is not recommended because it installs a program globally and can cause conflicts with other programs. Package installation can fail with error: externally-managed-environment (see error: externally-managed-environment). Instead, use UV or Pipx to install Python applications in isolated environments.
Use UV to run utilities
If you want to use Python to run stand-alone applications and utilities, install UV to install the newest Python and isolate any program in its own environment. UV is a new, unified tool that can be used both for programming projects and running utilities and tools. Use UV to install Python.
See the article:
UV provides commands uv tool install and the shorthand uvx command designed to run stand-alone Python applications and tools, replacing the older Pipx tool.
Or use Pipx
Alternatively, you can Install Pipx) to install Python and run stand-alone Python applications and tools. Pipx is an older, well-known tool designed to install and run Python command-line utilities globally but isolated from each other. See the article:
You can install Pipx with Homebrew and Python will be installed for you. This is an easy way to fix the error zsh: command not found: python but only if you want to run a Python program such as a utility or script.
For programming in Python
If you are starting a programming project with Python, you need to install Python and set up a development environment.
There are multiple ways to install Python on a Mac. You can install Python with Homebrew (not recommended) or use a Python version manager such as UV or Pyenv. I recommend:
If you're developing Python software projects, ask yourself if you're just going to develop one project or if you need to work on multiple Python projects. For a single project you can use brew python to install Python with Homebrew but you won't be able to easily switch between Python versions and updates to Homebrew-installed Python will break your dependencies. For multiple projects, including switching among Python versions, I recommend to install Python with UV, an all-in-one tool for managing Python projects. Alternatively, you can install Pyenv to manage Python versions but it's older and more cumbersome than UV.
Instructions for installing Python will explain how to set the $PATH in the .zprofile or .zshrc configuration file. This is necessary for the shell to find the Python command.
Fix error 'command not found: python'
If you're clear about why you are trying to run Python, either running a Python stand-alone application or coding in Python, you can now fix the error zsh: command not found: python. The solution will depend on whether Python is installed, where it is installed, and whether the Mac $PATH is set correctly.
Possible reasons for this error:
- You need to restart your Terminal ("reset the shell").
- A system Python is installed but not in the
$PATH. - A newer Python version is installed but not in the
$PATH. - Python is not installed.
Here is what went wrong:
- You may be following instructions that assume you have installed Python previously but you didn't.
- Maybe you installed Python previously but it is now missing.
- You need to restart the Terminal after installing Python and setting the
$PATH. - Most likely:
$PATHis not set in a~/.zprofileor~/.zshrcconfiguration file. Without a correct$PATH, the shell cannot find thepythoncommand.
You can read the article Mac Python PATH for more information about setting the $PATH for Python.
Restart your Terminal
Just to be sure that you don't have the simplest reason for an error, quit the Terminal application and launch the Terminal again. Then try:
$ python --version
It's an obvious solution but worth trying. A restart should display the Python version number.
If you still see zsh: command not found: python, read on.
Is the system Python installed?
Try python3 --version and which -a python3 to check if a system Python was installed with Xcode Command Line Tools.
$ python3 --version
Python 3.9.6
$ which -a python3
/usr/bin/python3
If you have Python 3.9.6 installed at /usr/bin/python3, you have the system Python installed by Xcode Command Line Tools. Don't install Python packages if you only have the the system Python. Instead, install another version of Python and set the Mac PATH.
If you really want to use the system Python (which I don't recommend), you can alias the python command to python3. Add the following line to your .zshrc file. See the article alias python3 to python for more information:
alias python='python3'
For this change to take effect, you'll either need to restart your terminal or reload your .zshrc file by entering source ~/.zshrc.
Is Python already installed?
Python can be installed in various ways: with the official installer, Homebrew, or a Python version manager such as UV or Pyenv. If you believe you have Python installed and you are getting the error zsh: command not found: python, you likely have a problem with the $PATH setting.
You will need to check the $PATH in the .zprofile or .zshrc or ~/.zshenv configuration files. By convention and design, the ~/.zprofile file is used for setting the $PATH (see .zshrc or .zprofile for an explanation). If you don't have a .zprofile file, check the .zshrc file or ~/.zshenv file.
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
Was Python was installed with the Python official installer?
The installer package from the Python website adds 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 is there, the official installer should have set the Mac PATH correctly, setting 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 UV (see update Python).
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.
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 other reasons but it is not needed to install Python.
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 if you have Python installed by Homebrew.
Python installed with Pyenv
Pyenv is a popular Python version manager for installing multiple Python versions and switching between them. It is typically installed using Homebrew. If you have Homebrew installed, you can check if Pyenv is installed:
$ brew list | grep pyenv
pyenv
Unless you need to follow a tutorial or get familiar with older Python tools, I recommend using UV instead of Pyenv as a Python version manager.
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/daniel/.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 for versions installed by Pyenv.
Python installed with UV
UV is a single coherent setup and package management system for Python, eliminating the need for separate tools such as pip, pip-tools, pipx, poetry, pyenv, or virtualenv. For running comand-line utilities or programming in Python, UV is the best tool to install Python and software packages. UV is written in the Rust language, making it extremely fast (10-100x faster than other tools).
Check if UV is installed:
$ uv --version
uv 0.6.14
If Python was installed with UV, you can list installed Python versions:
uv python list --only-installed
This will show any Python versions installed via UV, other installers, or the system Python.
The UV installer will run its own utility to modify your shell ~/.zshenv configuration file to ensure UV and its Python versions are on your PATH. However, the automatic behavior can be disabled. Many developers prefer to set the PATH in the ~/.zprofile shell configuration file, rather than the ~/.zshenv file.
If you want to set the PATH manually, or you've installed UV using Homebrew, you must set the Mac PATH to make sure UV is available on the commnd line. Add this command as the last line of your ~/.zprofile configuration file to configure the Zsh shell for UV.
export PATH="~/.local/bin:$PATH"
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 if you've installed Python using UV.
Checking the PATH
After resetting your shell, you can check the $PATH setting.
$ echo $PATH
~/.local/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin
This example shows the directory where UV installs Python.
The leftmost directory takes precedence over other directories. Your PATH should contain the directory that contains a Python executable or an alias to a Python executable.
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.