Comprehensive Guide to Fixing "zsh: command not found: python" Error in macOS Monterey 12.3

Problem Background and Error Analysis

With the release of macOS Monterey 12.3, many developers encountered a perplexing terminal error: zsh: command not found: python. This error typically occurs when attempting to execute Python code through Atom editor's atom-python-run package, despite Python 3.10.3 being correctly installed.

The root cause lies in Apple's removal of the system-provided Python 2.7 installation in macOS 12.3. Previously, the system provided a Python 2.7 interpreter at /usr/bin/python, and many tools and scripts relied on this path to invoke Python. After removal, any attempt to call the python command fails because the command no longer exists in the system path.

Solution Implementation Steps

After extensive testing, the following approach has proven to be the most effective solution:

Step 1: Reinstall Python via Homebrew

First, uninstall any previously installed Python versions from python.org, then reinstall using the Homebrew package manager:

brew install python

This installs the latest Python 3 version and places its executable in the /usr/local/bin directory, typically named python3.

Step 2: Create Python Alias

To address tools that still call python instead of python3, create an alias in the zsh configuration file:

echo "alias python=/usr/bin/python3" >> ~/.zshrc

This command appends the alias definition to the end of the .zshrc file, ensuring it takes effect every time a new terminal session starts.

Step 3: Reload Configuration

To make changes effective immediately, reload the zsh configuration:

source ~/.zshrc

Alternatively, completely close and reopen the terminal application.

Technical Principles Deep Dive

PATH Environment Variable Mechanism

When entering a command in the terminal, the system searches for executable files in the order defined by the PATH environment variable. In macOS, typical PATH settings include:

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

The system Python 2.7 was originally located at /usr/bin/python, but this location is now empty, causing command lookup failures.

Alias vs Symbolic Link Differences

The created alias is essentially a shell-level command redirection, different from symbolic links created at the filesystem level. When typing python, zsh interprets it as /usr/bin/python3, without affecting other applications that might depend on the python command elsewhere in the system.

Homebrew Installation Path Analysis

Python installed via Homebrew typically resides at /usr/local/bin/python3. This directory has higher priority in PATH than system directories, ensuring custom-installed software takes precedence over system software.

Atom Editor Integration Configuration

For developers using Atom editor, it's necessary to check the atom-python-run package settings:

Although the package settings might specify the Python interpreter path, in some cases the package still falls back to using the simple python command. Through the alias solution described above, you can ensure that regardless of how the package calls Python, it correctly points to the Python 3 interpreter.

It's recommended to explicitly specify the full Python interpreter path in atom-python-run settings:

/usr/bin/python3

This avoids reliance on shell PATH resolution, providing a more stable execution environment.

Alternative Solutions Comparison

Using pyenv for Multi-version Python Management

Another viable solution is using pyenv to manage Python versions:

brew install pyenv
pyenv install 3.10.3
pyenv global 3.10.3
eval "$(pyenv init --path)"

This approach is more suitable for development environments requiring management of multiple Python versions, though configuration is relatively more complex.

Direct Symbolic Link Approach

You can also create symbolic links to simulate the original python command:

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

However, this method requires administrator privileges and may affect system integrity verification.

Verification and Testing

After implementing the solution, verify the configuration is correct using these commands:

python --version
which python

Correct output should display Python 3.x version information and point to the /usr/bin/python3 path.

Create a simple test script in Atom:

print("Hello, World!")
import sys
print(f"Python version: {sys.version}")

Execute via atom-python-run to confirm normal operation and expected output.

Preventive Measures and Best Practices

To prevent similar issues in the future, consider these preventive measures:

• Use virtual environments (venv) to isolate dependencies in projects

• Explicitly specify Python interpreter paths in scripts (#!/usr/bin/env python3)

• Regularly check and update development environment configurations

• Use version control tools to track environment changes

By following these best practices, you can ensure stability and reproducibility in your Python development environment.