Python

audience developer
level all
topic Python
subtopic Installation

Brew Install Python

Brew Python. How to install Python with Homebrew on Mac.

If you need Python for casual use, it's easy to install Python with Homebrew, the Mac software package manager. Homebrew-installed Python is adequate for running scripts. However, it has drawbacks (described below) and you may want to consider other options to install Python on a Mac.

Before you get started

You'll need a terminal application to use Homebrew and install 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.

Drawbacks of Homebrew-installed Python

  • Homebrew's automatic updates. Homebrew automatically updates its Python as a dependency for other packages, potentially breaking your projects.
  • Multiple projects may need different Python versions. Homebrew-installed Python is a single version and you may need to switch among different versions for different projects.
  • Problems with environment isolation. Homebrew provides a single Python environment, which can cause conflicts between projects. Pip, the Python package manager, will prevent installation of packages unless you first set up a virtual environment.

If you want to install and run standalone Python applications, you should install Pipx after installing Homebrew. Pipx is like Homebrew but for Python applications, isolating each application in its own environment to avoid dependency conflicts. You don't need to install Python first, as Pipx installation with Homebrew will install the latest Python as a dependency.

If you will be installing Python software libraries for any programming project, I recommend to install Python with Rye. Rye is a newer tool that supports switching Python versions and provides better package management with virtual environments. Alternatively, with Homebrew-installed Python, you'll need to use the tool Pip to install Python packages along with an environment manager such as Venv or Virtualenv. You can also install Python with Pyenv, installing Homebrew as a first step, to allow switching among multiple Python versions.

Steps

If you haven't already installed it, you'll need to install Homebrew.

Here's how to install Python on Mac with Homebrew.

  1. Check macOS and update macOS if necessary.
  2. Check if Xcode Command Line Tools are installed.
  3. Install Homebrew.
  4. Install Python with brew install python.
  5. Set the Mac PATH for Python to make sure you use the correct version of Python.

This guide also covers Python build tools, including how to use a virtual environment and Pip, the package manager.

Pre-installed Python

You'll need Xcode Command Line Tools for software development, and with Xcode, Apple includes Python 3.9.6. As of October 2023, the latest Python version is 3.12.

You should not attempt to update or remove the system Python installed with Xcode Command Line Tools. Just install a newer Python version with Homebrew.

Check that Homebrew is ready

Before you install Python, check that Homebrew is ready.

  1. Use brew list to see all the packages in your local environment.
  2. Run brew update to update Homebrew.
  3. Run brew doctor to check that Homebrew is ready.

If Homebrew is not installed, you will see:

zsh: command not found: brew

See Zsh: command not found: brew for troubleshooting. Either Homebrew is not installed or the Mac PATH is not set in a ~/.zprofile or ~/.zshrc configuration file. Without a correct $PATH, the shell cannot find the brew command.

Brew list

Use brew list to see all the packages in your local environment.

$ brew list

It's good to see what you've installed previously so you can check again after you install Python.

Brew update

Before you install any software package with Homebrew, run brew update to update Homebrew. Updating Homebrew can take many minutes, so run the update before trying to install a package. It is better to run the update yourself rather than waiting for Homebrew to run the updates automatically. This will update any core dependencies that your package may need.

$ brew update
Already up-to-date.

Homebrew core packages are updated as often as every day, so it is likely you will see updates.

Brew doctor

Before you install any software package with Homebrew, run brew doctor to check that Homebrew is ready to install a package.

$ brew doctor
Your system is ready to brew.

Brew install

Now you can install Python with brew install python.

$ brew install python
==> Downloading https://ghcr.io/v2/homebrew/core/python/3.12/manifests/3.12.2_1
######################################################################### 100.0%
==> Fetching dependencies for [email protected]: mpdecimal, ca-certificates, openssl@3, readline, sqlite and xz
.
.
.
==> Installing [email protected]
==> Pouring [email protected]_1.arm64_sonoma.bottle.tar.gz
==> /opt/homebrew/Cellar/[email protected]/3.12.2_1/bin/python3.12 -Im ensurepip
==> /opt/homebrew/Cellar/[email protected]/3.12.2_1/bin/python3.12 -Im pip install -v
.
.
.
==> Summary
🍺  /opt/homebrew/Cellar/[email protected]/3.12.2_1: 3,239 files, 65.5MB
.
.
.
==> Caveats
==> [email protected]
Python has been installed as
  /opt/homebrew/bin/python3

Unversioned symlinks `python`, `python-config`, `pip` etc. pointing to
`python3`, `python3-config`, `pip3` etc., respectively, have been installed into
  /opt/homebrew/opt/[email protected]/libexec/bin

See: https://docs.brew.sh/Homebrew-and-Python

The console will show the downloaded files and dependencies. The console shows the location of the installed package. The console also shows post-install instructions labelled "Caveats." It is important to read the "Caveats" though sometimes they are cryptic. In the caveats, Homebrew explains that entering python without a version number on the command line will run the installed Python 3 version of Python. However, it doesn't explain that you must set the Mac PATH for the Homebrew version of Python.

Install a specific Python version with Homebrew

You may wish to install a specific version of Python using Homebrew. For example, Python 3.12 may be the newest version installed by Homebrew but you need to work on an application that requires Python 3.7. You can use brew search python to see if an earlier Python version is available. Unfortunately, Homebrew only provides a few recent versions of Python. Really, it's better to use Homebrew to install a version manager that allows installation and switching among different versions. You can Install Python with Rye if you need to work with multiple versions of Python.

Prior to Homebrew version 2.6.0, released in December 2020, Homebrew contained a brew switch command that allowed switching between package versions. As of Homebrew 2.0.0, when it began removing old packages automatically after brew upgrade and running brew cleanup every thirty days to remove packages that are no longer current, brew switch became less useful and was deprecated and removed.

Verify with brew list

After installing Python, use brew list python to verify that it has been installed. You'll see all the installed files.

$ brew list python

You can also see a list of dependencies for Python.

$ brew deps python
ca-certificates
mpdecimal
openssl@3
readline
sqlite
xz

Brew pin

Homebrew may upgrade Python to a newer version at any time. Some packages (particularly programming languages such as Ruby or Python) are dependencies of other packages. They may be automatically upgraded during the installation of another package. If you must use only the currently installed version of Python, you can block automatic updates using brew pin python. Here's how to pin Python so that a newer version cannot be automatically installed:

$ brew pin python

The command will not show a response but you can verify with brew info python.

$ brew info python
==> [email protected]: stable 3.12.2 (bottled) [pinned at 3.12.2_1]
.
.
.

You can remove the pin when you wish to install a newer version of a package.

$ brew unpin python
$ brew info python
==> [email protected]: stable 3.12.2 (bottled)
.
.
.

You'll need to run brew info python to see the changed status.

Upgrade Python with Homebrew

Use brew upgrade python to upgrade to the newest version of Python.

$ brew upgrade python

Note that brew update and brew upgrade are different. Update is for Homebrew itself. Upgrade is for individual software packages.

If you want to remove Python, see Uninstall a Homebrew package to uninstall (delete or remove) Python.

Set the $PATH for Homebrew Python

There's one final important step before your Homebrew-installed Python is available for use. You must set the Mac PATH to make sure you access the correct version of Python. Otherwise, entering the command python will trigger zsh: command not found: python and the command python3 will access the Xcode-installed Python version.

You can use TextEdit, the default macOS graphical text editor, to edit the ~/.zprofile file. Alternatively, you can edit the ~/.zshrc file. It works the same but, by convention and design, the ~/.zprofile file is used for setting the $PATH (see .zshrc or .zprofile for an explanation). You can open a file in TextEdit from the terminal:

$ open -e ~/.zprofile

You also can use the command line editors nano or vim to edit the shell configuration files. See Shell Configuration for more about editing shell configuration files.

The export command sets environment variables in the zsh shell. Here's how to set the $PATH for the Homebrew-installed Python:

export PATH="$(brew --prefix python)/libexec/bin:$PATH"

Add the new export directive as the last line in the ~/.zprofile file so the Homebrew-installed Python will take precedence over other versions. The new $PATH variable will be exported to the environment as a combination of the previous $PATH plus a new directory. The new directory comes first; it will take precedence over any directories present in the previous $PATH. A : colon character separates the new directory path from the existing directories in the previous $PATH.

You'll need double quotes because the PATH contains spaces or special characters. We use $(brew --prefix python) to programmatically obtain the location of the Homebrew Python installation so newer Homebrew installations won't require changes to the $PATH.

Changes to the ~/.zprofile file will not take effect in the Terminal until you've quit and restarted the terminal. Alternatively (this is easier), you can use the source command to reset the shell environment:

$ source ~/.zprofile  # Or just restart your terminal

The source command reads and executes a shell script file, in this case resetting the shell environment with your new $PATH setting.

Verify Python Installation

Check that Python is available:

$ python --version
Python 3.12.2

If you see zsh: command not found: python, check that the Mac PATH is set correctly.

Check that the python3 command gives you the Homebrew-installed version, not the Xcode-installed version:

$ python3 --version
Python 3.12.2

You should also see the Homebrew-installed version of Python with which python:

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

You've successfully installed Python with Homebrew. If this seems complicated, it is. It gets more complicated when you need to switch Python versions or install Python packages. If you need to set up your projects to switch Python versions, see Install Pyenv or Install Rye.

Install Python packages

Package managers allow you to download, install, and update software libraries and their dependencies. Pip is the standard package manager for Python, included with any version of Python since Python 3.3. After installing Python with Homebrew, pip should be available on the command line.

$ pip --help

You can attempt to install any Python package from the Python Package Index. Here we'll try to install the cowsay utility.

$ pip install cowsay
error: externally-managed-environment

However, you'll get error: externally-managed-environment if you are not using Pyenv or an environment manager. Recent versions of pip implement PEP 668 to encourage the use of virtual environments and prevent attempts to install a package into a system Python. See error: externally-managed-environment.

Create a project

Before creating a virtual environment, let's create a folder for a Python project. Then change directories to the project root.

$ mkdir myproject
$ cd myproject

We'll use the Venv environment manager for local project installations of packages with pip.

Environment managers

Use an environment manager to create a virtual environment for project isolation.

Environment managers are needed because pip installs packages globally which can lead to conflicts (dependency hell). Other software languages (JavaScript or Ruby, for example) provide options to install packages locally (within a single project) as well as globally (system-wide for all projects). There are two Python tools for creating virtual environments and using different versions of packages. Venv is a built-in Python package. Virtualenv is a more powerful tool with additional features. These tools allow pip to install Python packages into a virtual environment with its own installation directories, that doesn’t share libraries with other virtual environments.

If you use Rye as an all-in-one tool, you won't need venv or virtualenv for environment management and you can install packages directly with Rye.

If you decide to install packages with pip and use venv, you should run brew pin python to prevent automatic Python upgrades. When Homebrew upgrades Python, virtual environments will break.

Assuming we're in the project directory myproject, we'll set up venv to eliminate the error: externally-managed-environment when using pip.

$ python -m venv ./env
$ source ./env/bin/activate

The python -m venv command creates a ./env that contains project configuration files and utilities.

Now you can install any Python package from the Python Package Index. Here we'll install the cowsay utility.

$ pip install cowsay
Collecting cowsay
Using cached cowsay-6.1-py3-none-any.whl.metadata (5.6 kB)
Using cached cowsay-6.1-py3-none-any.whl (25 kB)
Installing collected packages: cowsay
Successfully installed cowsay-6.1

Run Python

After installing a package within the virtual environment, you can use the Python interpreter interactively (the REPL or Read-Eval-Print Loop).

$ python
Python 3.12.1 (main, Jan  7 2024, 23:31:12) [Clang 16.0.3 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import cowsay
>>> cowsay.cow('Hello World')
___________
| Hello World |
  ===========
           \
            \
              ^__^
              (oo)\_______
              (__)\       )\/\
                  ||----w |
                  ||     ||
>>>

Enter quit() or type Control + D to exit the Python interpreter.

I recommend comparing the Homebrew-installed Python approach to Install Python with Rye, as I believe it's better to use a single tool to manage Python projects.

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.