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.
- Check macOS and update macOS if necessary.
- Check if Xcode Command Line Tools are installed.
- Install Homebrew.
- Install Python with
brew install python
. - 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.
- Use
brew list
to see all the packages in your local environment. - Run
brew update
to update Homebrew. - 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.