This page describes how Python is handled in Homebrew for users. See Python for Formula Authors for advice on writing formulae to install packages written in Python.
Homebrew should work with any CPython and defaults to the macOS system Python.
Homebrew provides formulae to brew Python 3.x and a more up-to-date Python 2.7.x.
Important: If you choose to install a Python which isn’t either of these two (system Python or brewed Python), the Homebrew team cannot support any breakage that may occur.
Homebrew provides one formula for Python 3.x (
python) and another for Python 2.7.x (
The executables are organised as follows so that Python 2 and Python 3 can both be installed without conflict:
python3points to Homebrew’s Python 3.x (if installed)
python2points to Homebrew’s Python 2.7.x (if installed)
pythonpoints to Homebrew’s Python 2.7.x (if installed) otherwise the macOS system Python. Check out
brew info pythonif you wish to add Homebrew’s 3.x
pip3points to Homebrew’s Python 3.x’s pip (if installed)
pip2point to Homebrew’s Python 2.7.x’s pip (if installed)
Setuptools can be updated via pip, without having to re-brew Python:
python -m pip install --upgrade setuptools
Similarly, pip can be used to upgrade itself via:
python -m pip install --upgrade pip
pip install --user
pip install --user is disabled for brewed Python. This is because of a bug in distutils, because Homebrew writes a
distutils.cfg which sets the package
A possible workaround (which puts executable scripts in
python -m pip install --user --install-option="--prefix=" <package-name>
site-packages is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here:
So, for Python 3.y.z, you’ll find it at
Python 3.y also searches for modules in:
site-packages directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon
brew install python.
The reasoning for this location is to preserve your modules between (minor) upgrades or re-installations of Python. Additionally, Homebrew has a strict policy never to write stuff outside of the
brew --prefix, so we don’t spam your system.
Some formulae provide Python bindings. Sometimes a
--with-python@2 option has to be passed to
brew install in order to build the Python bindings. (Check with
brew options <formula>.)
Warning! Python may crash (see Common Issues) if you
import <module> from a brewed Python if you ran
brew install <formula_with_python_bindings> against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with Python bindings (e.g.
These should be installed via
pip install <package>. To discover, you can use
pip search or https://pypi.python.org/pypi.
Note: macOS’s system Python does not provide
pip. Follow the pip documentation to install it for your system Python if you would like it.
For brewed Python, modules installed with
python setup.py install will be installed to the
$(brew --prefix)/lib/pythonX.Y/site-packages directory (explained above). Executable Python scripts will be in
The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to run:
CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <package>
WARNING: When you
brew install formulae that provide Python bindings, you should not be in an active virtual environment.
Activate the virtualenv after you’ve brewed, or brew in a fresh terminal window.
Homebrew will still install Python modules into Homebrew’s
site-packages and not into the virtual environment’s site-package.
Virtualenv has a
--system-site-packages switch to allow “global” (i.e. Homebrew’s)
site-packages to be accessible from within the virtualenv.
Formulae that declare an unconditional dependency on the
"python@2" formulae are bottled against Homebrew’s Python 3.x or 2.7.x and require it to be installed.