Python

audience developer
level all
topic Python
subtopic Installation

Update Python

How to update Python on Mac. Upgrade Python versions. The MacOS system Python. Latest Python. Change Python default version. Set or switch Python. Options to install Python. Python version managers.

Python is extremely popular, especially for beginners. Until recently, a lack of standard development tooling made setting up Python complicated. And there are multiple ways to install Python, which can lead to confusion.

This guide explains how to upgrade Python on Mac. Before you start, consider three things:

  1. Are you using Python only to run a simple script? If so, you can use the system Python installed with Xcode Command Line Tools. But don't install any Python packages if you use the system Python.
  2. For installing packages for Python applications, install Pipx with Homebrew.
  3. Are you working on multiple programming projects? If so, you should use a Python version manager such as Rye (recommended) or Pyenv (popular).

Before you upgrade Python on a Mac, check if Python is already installed, make sure you know how it was installed, and ask yourself if you need to use a different approach to installation based on the differences outlined above.

Before you get started

You'll need a terminal application to update Python. 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.

Python versions

The current Python version is 3.13, as of October 2024. New releases of Python come yearly, typically released in October. The next version, Python 3.14, is expected in October 2025. The newest Python version is listed on the Python website.

Here are Python versions you may have on macOS.

  1. Macs prior to macOS 12.3 came with Python 2.7 pre-installed. Check macOS and update macOS if you have macOS 12.3 or older. Don't use any Python 2 version for development.
  2. When you install Xcode Command Line Tools, Apple includes Python 3.9.6. That's an older version, too. It's okay to use for simple scripts but don't install Python packages. If you're working on a programming project, leave the system Python in place and install a newer Python.

Here are options to install a single new Python version. These are not recommended.

  1. Install Python with Homebrew. It will give you a Python version that's easy to manage and remove. However, it's best just for running scripts. If you need to install packages, install Pipx (for applications), use Rye, or use Pyenv with Venv and Pip (for programming).
  2. Use the installer package from python.org (not recommended). It installs the latest Python version in the macOS /Library/Frameworks folder, adds symbolic links to /usr/local/bin, and modifies your Mac PATH. 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.

If you are working on multiple Python projects, you should install Python with a tool that manages multiple versions, creates a virtual environment to isolate dependencies, and installs packages.

Here are options to install Python with a version manager.

  1. Install Python with Rye. Rye is a new all-in-one tool for Python version and package management.
  2. Install Pyenv. Start by using Homebrew to install the Pyenv version manager. Then install pyenv-virtualenv, an environment manager. Install one or more Python versions and use Pip to install Python packages. Use this approach if you want to learn to use the built-in Python tools.

I recommend using Rye, the new all-in-one tool, as it simplifies Python development by focusing on managing projects without multiple tools.

Steps

Here's how to update Python on Mac.

  1. Check macOS and update macOS.
  2. Check if Xcode Command Line Tools are installed.
  3. Check if Python is installed.
  4. Find out where Python is installed.
  5. Update your Python version, or install Python again, depending on your needs.
  6. Set the Mac Python PATH to make sure you use the correct version of Python.

You can mix versions of Python from different sources (from Rye, Homebrew, Pyenv, the official installer, or the Xcode pre-installed version) if you set the Mac PATH correctly. Without a correct PATH, multiple sources of Python lead to conflicts and misery.

Is Python installed?

You can check to see if your Mac has Python.

$ python --version
zsh: command not found: python

You'll see zsh: command not found: python if Python is not available. See the article zsh: command not found python for help.

If Python is installed, you'll see a version number. Use which -a to see where Python is installed.

$ python --version
Python 3.12.2
$ which -a python
/Users/daniel/.pyenv/shims/python

The which -a command shows the path to the Python executable (in this case, a shim script that launches the Python executable).

Here are the most common locations for Python on a Mac.

  1. /usr/bin/python3 is the system Python installed with Xcode Command Line Tools. This is an alias; the actual location is /Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/bin.
  2. /opt/homebrew/opt/[email protected]/libexec/bin/python is the Homebrew Python.
  3. /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 is the Python installed with the official Python website installer.
  4. /Users/username/.pyenv/shims/python is the Python installed with Pyenv.
  5. /Users/username/.rye/shims/python is the Python installed with Rye.

Knowing the installed location of Python will show you how it was installed so you can update Python correctly. Instructions for each Python installation method are below.

Is the system Python installed?

You'll need Xcode Command Line Tools for software development, and with Xcode, Apple includes Python 3.9.6. You should install a newer version for running Python programs or programming and you shouldn't use the system Python -- it's for the system, not you.

If Python is not installed and you just want to run a Python script, you can Install Xcode Command Line Tools and alias python3 to python to use the system Python. However, in general, using the system Python for installing and running programs or developing software quickly gets complicated. Experts prefer to install Pipx to run programs or install Python separately and set up a proper development environment for programming.

You should not attempt to update or remove the system Python installed with Xcode Command Line Tools. You may not notice, but some minor Apple development utilities depend on the system Python.

Python installed with the Python installer

The command which -a python will show you the location of Python installed with the official Python website installer:

$ which -a python
/Library/Frameworks/Python.framework/Versions/3.12/bin/python3

You can upgrade Python installed with the Python installer by downloading the latest version from the Python website. You can download and install any version with the installer application.

I recommend using Rye instead of the Python installer. Rye is an all-in-one tool that provides a streamlined solution for Python development.

Update Python installed with Homebrew

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.

The command which -a python will show you the Homebrew Python location:

$ which -a python
/opt/homebrew/opt/[email protected]/libexec/bin/python

You can upgrade a Python version with Homebrew. You'll lose access to the old version, so use Rye or Pyenv if you need to switch among versions.

$ brew upgrade python

The command brew list will show you the newer version of Python.

You can use the Python installed by Homebrew for running simple scripts. With Homebrew, use Pipx to install Python programs for command-line utilities. Rye is better if you will be installing Python software libraries for any programming project.

Update Python installed with Rye

Rye is the new favorite for installing and managing Python because it offers a single coherent setup and packaging system, eliminating the need for separate tools such as pip, pyenv, and venv for managing versions, software libraries, and environments. If your project is more complex than a simple script or utility, use Rye to install Python and software libraries.

For instructions:

If Python was installed with Rye, you can list installed Python versions:

$ rye --version
rye 0.32.0
$ rye toolchain list
[email protected] (/Users/daniel/.rye/py/[email protected]/bin/python3)

This will show a Python version if it is installed via Rye. If you see zsh: command not found: rye you don't have Rye.

The command which -a python will show you the Rye shims location:

$ which -a python
/Users/username/.rye/shims/python

You can install newer Python versions with Rye. You'll be able to create separate projects with different Python versions. Each project will have its own package library installed by Rye.

See an article on how to create and manage Python projects with Rye.

Update Python installed with Pyenv

Pyenv is a popular Python version manager for installing multiple Python versions and switching between them. It is typically installed with Homebrew. If you have Homebrew installed, you can check if Pyenv is installed:

$ brew list | grep pyenv
pyenv

Note that I recommend using Rye instead of Pyenv as a Python version manager. Rye is an all-in-one tool that provides a streamlined solution for Python development.

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.

The command which -a python will show you the Pyenv shims location:

$ which -a python
/Users/username/.pyenv/shims/python

You can install newer Python versions with Pyenv. You'll be able to switch among Python versions. Each version will have its own package library.

Before you proceed, ensure that pyenv itself is up-to-date. If you installed pyenv via Homebrew, you can update it using the following command:

$ brew update && brew upgrade pyenv

This ensures that you have the latest version of pyenv which will include the most recent Python versions available for installation.

To see a list of Python versions that you can install with pyenv, use the following command:

$ pyenv install --list

This command displays all the Python versions you can install. Look through the list and identify the version you want to install.

Once you've decided on a version, you can install it using pyenv. For example, if you want to install Python 3.10.2, you would use the following command:

$ pyenv install 3.10.2

Replace "3.10.2" with the version of Python you wish to install.

After the installation is complete, you can set the newly installed Python version as the default version for your system using pyenv global. For example:

$ pyenv global 3.10.2

To verify that the new Python version is set correctly, you can use:

$ python --version

Or, specifically for pyenv, check the current version being used:

$ pyenv version

This should reflect the version you set using the pyenv global command.

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.