keepcalculator

06 Numbers and Powers

Upgrade Python Version on Mac: Full Guide

Card No. 06·74495 · Updated · Standard formula, shown below

To upgrade Python on a Mac, you need to install a newer version alongside your current one and then update your shell’s PATH so the new version is used by default. The safest method is using Homebrew (brew install python), which handles the installation and symlinking for you; alternatively, you can download the official installer from python.org.

Why Upgrade Python on macOS

macOS ships with a system Python (2.7 on older versions, 3.8.9 on Catalina and later) that Apple keeps for its own tools. That version is often outdated and lacks the latest security patches, performance improvements, and new language features. Upgrading gives you access to newer syntax, better type hints, faster interpreter performance, and compatibility with the latest versions of popular libraries like NumPy, pandas, and Django. It also ensures you are using a version that still receives security updates—Python 2.7 has been end-of-life since January 2020, and even Python 3.8 is no longer officially supported as of October 2024.

How Python Versions Work on macOS

Python on macOS can be installed in several ways, and each method places the executable in a different location. The system Python lives in /usr/bin/python3. Homebrew installs into /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel). The official installer from python.org puts Python in /Library/Frameworks/Python.framework/Versions/3.x/bin. When you type python3 in Terminal, macOS searches the directories listed in your PATH environment variable, in order, and runs the first match. Upgrading means either replacing the symlink that points to the current version or reordering your PATH so the new version comes first.

Check Your Current Python Version

Before upgrading, see what you have. Open Terminal and run:

python3 --version
which python3

The first command shows the version (e.g., Python 3.9.6). The second shows the full path to the executable, which tells you which installation you are using. If the path is /usr/bin/python3, you are using Apple’s system Python. If it is /opt/homebrew/bin/python3 or /usr/local/bin/python3, you are using a Homebrew-installed version. Also check if you have pyenv installed, as it manages multiple versions and may be overriding your default.

Method 1: Upgrade Using Homebrew (Recommended)

Homebrew is the most popular package manager for macOS. If you don’t have it, install it first from brew.sh. Then:

  1. Update Homebrew itself: brew update
  2. Upgrade Python: brew upgrade python
  3. If Python isn’t installed yet, install it: brew install python
  4. Check the new version: python3 --version

Homebrew automatically installs the latest stable Python and creates symlinks in /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel). Because those directories are usually ahead of /usr/bin in your PATH, the new version becomes the default. If you still see an old version, your PATH may be misconfigured (see the troubleshooting section below).

Method 2: Install from python.org

The official installer from python.org gives you a standalone Python that does not depend on Homebrew. Download the latest macOS installer (a .pkg file), double-click it, and follow the prompts. The installer puts Python in /Library/Frameworks/Python.framework and adds its bin directory to your PATH automatically. After installation, open a new Terminal window and run python3 --version to verify. This method is fine if you prefer the official distribution, but note that you will need to manually update it when new versions come out—there is no built-in update command.

Method 3: Use pyenv to Manage Multiple Versions

If you work on several projects that require different Python versions, pyenv is the best tool. It lets you install and switch between versions without touching your system Python. Install it with Homebrew:

brew install pyenv

Then add the following to your ~/.zshrc (or ~/.bash_profile if you use Bash):

export PATH="$HOME/.pyenv/shims:$PATH"
eval "$(pyenv init -)"

After restarting your shell, you can install a new version:

pyenv install 3.12.4
pyenv global 3.12.4

The global command sets the default version for your user. You can also set a per-directory version with pyenv local 3.11.9. This is the most flexible approach if you need to test code across multiple Python versions.

How to Choose Which Version to Upgrade To

As of mid-2025, the latest stable Python release is 3.12.x, with 3.13 in beta. For most users, the safest choice is the latest stable release (3.12.x) because it has the best library compatibility and active security support. If you rely on older third-party packages, check that they support the new version—some C extensions may need recompilation. You can check compatibility on the package’s PyPI page or by running your test suite after upgrading. If you are starting a new project, use the newest stable version; if you are maintaining an existing project, upgrade only after verifying your dependencies work.

Common Problems and How to Fix Them

After upgrading, you might encounter a few issues:

  • Still seeing the old version: Run which python3 to see what is being executed. If it points to /usr/bin/python3, your PATH does not include the new installation. Add the appropriate directory to your PATH in ~/.zshrc (e.g., export PATH="/opt/homebrew/bin:$PATH" for Homebrew on Apple Silicon).
  • pip is missing or outdated: After upgrading, run python3 -m pip install --upgrade pip to ensure pip matches the new Python version.
  • Virtual environments break: Virtual environments are tied to the Python version they were created with. Recreate them with python3 -m venv venv after upgrading.
  • Command not found: python (without the 3): On macOS, the python command is not available by default. Use python3 or create an alias in your shell configuration.
  • Homebrew says “python@3.12 is keg-only”: This means the formula is not symlinked into /opt/homebrew/bin. Run brew link --overwrite python@3.12 to force the symlink, but be aware this may override other Python installations.

Frequently Asked Questions

Is it safe to delete the old Python version?

Do not delete the system Python at /usr/bin/python3—macOS uses it for system tools like brew itself. If you installed Python via Homebrew, you can safely remove older versions with brew cleanup, but keep at least one version. If you used pyenv, you can uninstall old versions with pyenv uninstall 3.9.6.

Will upgrading Python break my existing projects?

It can, if your projects rely on deprecated features or old library versions. Python 3.x is largely backward-compatible, but minor breaking changes occur between releases (e.g., 3.10 removed some deprecated modules). Always test your projects after upgrading. Using virtual environments and pyenv makes it easy to switch back if something breaks.

How do I update pip after upgrading Python?

Run python3 -m pip install --upgrade pip. This ensures pip is installed for the new Python version and is up to date. If you use pip as a standalone command, it may point to an older Python; it’s safer to use python3 -m pip.

What is the difference between python and python3 on macOS?

On macOS, python usually does not exist unless you create an alias or install a version that provides it. python3 explicitly invokes Python 3.x. Using python3 avoids confusion with legacy Python 2 scripts, which are no longer supported.

Do I need to upgrade if I only use Anaconda?

If you use Anaconda or Miniconda, you manage Python through conda environments. You can update Python within a conda environment with conda install python=3.12. Upgrading the system Python is not necessary for conda users, but you should keep your base environment updated.

Final Thoughts

Upgrading Python on a Mac is straightforward with Homebrew or pyenv. The key is to verify your PATH and test your projects after upgrading. If you are new to Python, start with the latest stable version and use virtual environments to keep dependencies isolated. For production systems, always test the upgrade in a staging environment first.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →