How can I fix the "zsh: command not found: python" error? (macOS Monterey 12.3, Python 3.10,...

Fixing 'zsh: command not found: python' on macOS Monterey

A comprehensive guide to resolving the 'zsh: command not found: python' error on macOS Monterey with Python 3.10, especially when using Atom IDE and atom-python-run.

Encountering 'zsh: command not found: python' is a common frustration for developers on macOS, particularly after system updates or when setting up a new environment. This error indicates that your shell (Zsh, the default on modern macOS versions) cannot locate the python executable in its defined PATH. This article will guide you through diagnosing and fixing this issue, focusing on macOS Monterey (12.3) with Python 3.10, and how it impacts development environments like Atom IDE with the atom-python-run package.

Understanding the 'command not found' Error

The 'command not found' error means that when you type python in your terminal, Zsh searches through a list of directories specified in your PATH environment variable. If it doesn't find an executable named python in any of those directories, it reports the error. This often happens because:

1. Python 2 vs. Python 3: macOS historically included Python 2. Python 3 installations (especially via Homebrew or official installers) often install python3 and pip3, but not necessarily a python alias or symlink.
2. Incorrect PATH: The directory where Python 3 is installed might not be included in your shell's PATH.
3. Shell Configuration: Your shell's configuration file (.zshrc for Zsh) might not be correctly sourcing the necessary environment variables.
4. IDE/Package Specifics: Tools like Atom's atom-python-run package rely on the system's PATH or specific configurations to find the Python interpreter.

flowchart TD
    A[User types 'python' in Zsh] --> B{Is 'python' in PATH?}
    B -- No --> C[Error: 'command not found']
    B -- Yes --> D{Is 'python' a valid executable?}
    D -- No --> C
    D -- Yes --> E[Python interpreter runs]

Flowchart of how Zsh resolves a command

Diagnosing Your Python Installation

Before attempting fixes, it's crucial to understand what Python versions are installed and where they are located. This will help you determine the best course of action.

which python
which python3
python --version
python3 --version

Commands to check Python installations and versions

If which python returns nothing or an error, that's the core of your problem. which python3 should ideally point to your Python 3.10 installation (e.g., /usr/local/bin/python3 if installed via Homebrew).

Step-by-Step Solutions

Here are the most effective ways to resolve the 'zsh: command not found: python' error, starting with the most common and recommended approaches.

1. 1. Verify Homebrew Installation (Recommended)

If you installed Python 3.10 via Homebrew, ensure Homebrew's binaries are in your PATH. Homebrew typically installs Python 3 as python3. You can create a symlink or alias for python to point to python3.

First, check your Homebrew installation:

brew doctor

If brew doctor suggests adding Homebrew to your PATH, follow its instructions. This usually involves adding lines to your ~/.zshrc file. For Apple Silicon Macs, this might be:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

For Intel Macs, it's typically:

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/usr/local/bin/brew shellenv)"

After updating ~/.zshrc, restart your terminal or run source ~/.zshrc.

2. 2. Create a Symlink or Alias for Python 3

If python3 works but python doesn't, you can create a symbolic link (symlink) to make python point to python3. This is often the cleanest solution.

First, find the path to your python3 executable:

which python3

Let's assume it returns /usr/local/bin/python3 (common for Homebrew). Now, create the symlink:

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

Warning: Be cautious when using sudo and creating symlinks in system directories. Ensure you're linking to the correct Python 3 version. Alternatively, you can add an alias to your ~/.zshrc:

echo 'alias python="python3"' >> ~/.zshrc
source ~/.zshrc

This alias will only work within your Zsh shell and not for applications that don't source your shell environment.

3. 3. Adjust Your Zsh PATH

Manually add the directory containing your Python 3 executable to your PATH in ~/.zshrc. This is useful if Python was installed via an official installer or a custom location.

Open ~/.zshrc with your preferred text editor (e.g., nano ~/.zshrc or code ~/.zshrc). Add the following line, replacing /path/to/your/python/bin with the actual directory where python or python3 resides (e.g., /Library/Frameworks/Python.framework/Versions/3.10/bin):

export PATH="/path/to/your/python/bin:$PATH"

Save the file, then apply the changes:

source ~/.zshrc

4. 4. Configure Atom IDE and atom-python-run

The atom-python-run package relies on finding the Python interpreter. If your system's PATH is correctly configured, Atom should pick it up. However, sometimes Atom's environment differs from your terminal's.

1. Check atom-python-run settings: Go to Atom -> Preferences -> Packages, search for atom-python-run, and click 'Settings'. Look for an option to specify the Python executable path. You might need to explicitly set it to /usr/local/bin/python3 or /usr/local/bin/python (if you created the symlink).
2. Restart Atom: After making any system PATH changes or package setting adjustments, always restart Atom completely to ensure it reloads the environment variables.
3. Install script package: Some users find the script package (another Atom package) more reliable for running Python scripts, as it often has better environment handling. You can try installing it and configuring it similarly.

Verifying the Fix

After applying any of the solutions, open a new terminal window and run the following commands to confirm the fix:

python --version
which python

# If using Atom, try running a simple Python script:
# print("Hello from Python!")

Verifying Python installation and version

You should now see Python 3.10.x as the output for python --version, and which python should point to your desired Python 3 executable. If you're still facing issues, double-check your ~/.zshrc for typos and ensure no conflicting PATH entries are present.