How Can I Fix the “zsh: command not found: python” Error

If you’ve ever opened your terminal, typed python --version (or just python), and got greeted with an unhelpful message like:

zsh: command not found: python

You’re not alone. It’s frustrating: you’re ready to dive into code, but the shell seems to have forgotten how to “python”. I’ll walk you through what’s going on, why it happens, and how you can fix the “zsh: command not found: python” error in a clear, friendly way. I’ll compare popular blog posts on the topic, point out what they miss, and then deliver a more detailed solution with extra tips that they didn’t include. Grab your favourite drink, let’s get your terminal back to behaving.

Check Whether Python is Already Installed

Before making changes, let’s see what you have.

Open your terminal and run:

which python
which python3

• If which python returns nothing (empty), that means python is not found in any folder listed in your PATH.
• If which python3 returns something like /usr/bin/python3 or /usr/local/bin/python3, you already have Python 3 installed.
• Then run: python3 --version to check the version.

If you see something like Python 3.12.4, great you have Python3 installed. The key issue is that the python command (without “3”) might not be set up. This is very common on Mac and Linux nowadays. For example, many Mac users report that only python3 works, but python gives “command not found”.

If neither python nor python3 respond, then you likely don’t have Python installed (or installed in a non-standard location). That means you’ll need to install. We’ll cover that next.

Installing Python:

On macOS

• You can go to the official Python website and download the macOS installer.
• Or you can use Homebrew (popular package manager) and run: brew install python This installs a Python3 environment. Many blog posts suggest this.

On Linux (Ubuntu, Debian, etc.)

• Often you can run: sudo apt update sudo apt install python3 sudo ln -s /usr/bin/python3 /usr/local/bin/python to install Python3 and create a python alias.
• Or use your distribution’s package manager.

Once installed, run python3 --version (or python --version if you created a link) to verify. If you still see “command not found”, then you’ll need to adjust your PATH or alias (see next steps).

Decide How You Want to Run The python Command

There are three common approaches:

(A) Use python3 explicitly
Many people just accept that python means Python 2 (old) and run python3 for Python 3. If you’re fine doing that, you can continue that way. Then your error message disappears simply because you use python3 instead of python.

(B) Create an alias so python runs python3
If you want convenience (type python not python3), you can add an alias. In your ~/.zshrc (for Zsh) add:

alias python=python3

Save and then run:

source ~/.zshrc

to load it immediately. After that, python --version should behave like python3 --version. A lot of blogs suggest this quick fix.

Step 4: Fixing the PATH or shell config if python still not found
Alternatively, you might create a symbolic link so the system treats python as an actual executable pointing to python3. For example:

sudo ln -s /usr/local/bin/python3 /usr/local/bin/python

This way any scripts expecting python will work without alias issues. Some users on Mac have done this.

Which one you choose depends on your comfort level, whether scripts expect python, and how tidy you want your environment.

Fix the PATH or Shell Config if Python Still Not Found

Sometimes you’ve installed Python, added an alias, but you still get that “command not found” error. Here are deeper checks:

1. Check where your Python is installed which python3 If it returns something like /usr/local/bin/python3 or /opt/homebrew/bin/python3, note the path.
2. Check your PATH environment variable echo $PATH See if the directory containing python3 is listed. If it’s omitted, Zsh can’t find the executable in its search path.
3. Edit ~/.zprofile or ~/.zshrc
   On macOS, some installations require you to add lines like: export PATH="/usr/local/bin:$PATH" or export PATH="/opt/homebrew/bin:$PATH" depending on where Homebrew installed Python. This ensures that /usr/local/bin or /opt/homebrew/bin is searched first. mac.install.guide+1
4. Reload your shell
   After editing config files, either close and reopen your terminal, or run: source ~/.zshrc or source ~/.zprofile so changes take effect immediately.
5. Check again python --version or python3 --version Now the python command should resolve. If not, revisit the path, alias, or link.

Using a Version Manager

If you’re developing a lot of Python projects, you might want to switch between Python versions easily. This is where a version manager like pyenv comes in. Many blog posts mention this but don’t detail it deeply.

With pyenv you can:

• Install multiple Python versions (e.g., 3.10.8, 3.11.5)
• Set a global default version (pyenv global 3.11.5)
• Set a local version for a project directory (pyenv local 3.10.8)
• And pyenv will symlink a python command that points to the selected version.

How to set up (on Mac with Homebrew):

brew install pyenv
pyenv install 3.11.5
pyenv global 3.11.5

Then add to ~/.zprofile:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"

Restart your shell and run python --version. This gives you full control. It’s more work than a simple alias, but if you switch versions often, it’s worth it.

Troubleshooting common stubborn cases:

If you still see “zsh: command not found: python”, here are some specific things to check:

• You installed python3 but forgot alias or link: So python3 works, but python still fails. Use alias or link as we covered.
• Your ~/.zshrc isn’t being loaded: Some people use ~/.zprofile or ~/.zshenv instead. Try editing each.
• You edited the file but forgot to reload or restart: Changes don’t apply until you source the file or reopen terminal.
• Symbolic link points to wrong path: If you created ln -s …, make sure the source path exists, e.g., /usr/local/bin/python3.
• Scripts or tools expect python2: Rare today, but if you have legacy code expecting python2, you may need specific installation of the older version. Some blog posts mention installing Python2 for very old Mac versions.
• Your shell is using a login profile vs interactive profile: On Mac, sometimes ~/.zprofile is read for login shells (open Terminal), and ~/.zshrc for interactive shells. Ensure both include the alias or PATH if needed.
• You are using a virtual environment: If you activated a virtualenv, then python should work inside that env. But if activation failed, it may still break.

Conclusion

The “zsh: command not found: python” error is an annoyance, but it’s totally fixable. Once you understand what’s happening your shell can’t find a python executable in its path you can pick a fix that suits your workflow: use python3, alias python, or link it properly. If you’re doing Python development and juggling versions, go with a version manager like pyenv.