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. Plus there are mnay 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 extras, such as Python libraries or packages, if you use the system Python.
  2. For installing stand-alone Python applications, install Pipx with Homebrew.
  3. Are you working on a programming project? If so, you should use a Python version manager such as UV (recommended) or Pyenv (popular).

Before you try to 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. Read on for recommendations (below).

  1. You can install Python with Homebrew. Homebrew will give you a Python version that's easy to manage and remove. However, it's best just for running simple scripts. For running applications, install Pipx. For programming, use UV (the new unified tool) or install Pyenv with Venv and Pip.
  2. You can 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 programming with Python, you should install Python with a tool such as UV that manages multiple versions, creates a virtual environment to isolate dependencies, and installs packages. For an explanation of the role of version management, virtual environments, and package installation in Python, see my Mac Python general guide.

Here are options to install Python for programming:

  1. Install Python with UV (recommended). UV is a new, fast, unified tool for Python version, environment, 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 conventional Python 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.

Xcode Command Line Tools are required before installing Python (or any other programming language) because Python installation methods need basic Unix utilities that are not included by default in the macOS.

The Mac Path is an environment variable that controls where the operating system looks for executables. You can mix versions of Python from different sources (from UV, 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.13.3
$ which -a python
/Users/daniel/.local/bin/python

The which -a command shows the path to the Python executable (in this case, the version installed with UV).

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.13/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 (an older all-in-one tool).
  6. /Users/username/.local/bin/python is the Python installed with UV.

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. The system Python has several limitations:

  1. It's an older version (3.9.6) that lacks newer language features and optimizations
  2. Apple uses it for their own system scripts and utilities, so modifying it could break macOS functionality
  3. System updates may overwrite your changes or installed packages
  4. It has restricted permissions that can cause permission errors when installing packages

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.13/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 UV instead of the Python installer because it's faster and the installation locations follow better macOS development practices. The system directories /usr/local/bin and /Library/Frameworks used by the official Python installer require administrator privileges, can affect all users on the machine, and may be modifed by system updates.

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.

$ 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, add Pipx to install Python programs for command-line utilities. Switch from Homebrew-installed Python to UV or Pyenv/Venv/Pip for programming projects.

Update Python installed with UV

UV is the new favorite for installing and managing Python because it offers a single coherent setup and packaging system that's 10-100x faster than previous tools, 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 UV to install Python and software libraries.

Check if UV is installed:

$ uv --version
uv 0.6.14

If you see zsh: command not found: uv you don't have UV. See the article Install Python with UV.

The command which -a python will show you which Python versions are available to the command line:

$ which -a python
/Users/username/.local/bin/python

UV provides a command to show the directory that contains the actual Python executables:

$ uv python dir

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

To list all installed and available Python versions:

uv python list

To exclude downloadable versions and only show installed Python versions:

uv python list --only-installed

This will show any Python versions installed via UV, other installers, or the system Python.

To install the latest Python version with UV:

$ uv python install --preview

To install an older Python version with UV:

$ uv python install 3.12 --preview

You can remove Python versions:

$ uv python uninstall 3.12

See an article on how to install and manage Python with UV.

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

Unless you need to follow a tutorial or get familiar with older Python tools, I recommend using UV instead of Pyenv as a Python version manager.

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.13.3

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.12.2, you would use the following command:

$ pyenv install 3.12.2

Replace "3.12.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.12.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.