Homebrew and Python

Python is a powerful and beautiful interpreted language.

Overview

Homebrew is designed to work - or should work ;-) - with any CPython, in particular with OS X system's Python, but also provides formulae to brew a more up-to-date Python 2.7.x. However, if you choose to use another Python than these two alternatives (system Python or brewed Python), the Homebrew team cannot support you with issues.

Brewed Python

We recommend to brew install python because:

• Comes with pip (and distribute)
• Python (distutils) finds brewed software (includes, libs), knows about the compiler and flags even if the command line tools for Xcode are not installed.
• No need to set the PYTHONPATH for Homebrew bindings.
• No need to work-around the sudo-is-needed-for-easy_install issue, described there --> Gems, Eggs and Perl Modules.

Python 2.x or Python 3.x

Homebrew provides a formula for Python 2.7.x and one for Python 3.x. They don't conflict, so they can both be installed. The executable python will always point to the 2.x and python3 to the 3.x version. But which version should I use?

As the time of writing (Dec. 2012), almost all bindings are installed for Python 2.x only - even if the software supports Python 3.x. There is an issue to discuss this topic.

Distribute, Pip, etc.

The Python formula installs Pip and Distribute, the latter of which provides easy_install.

Distribute can be updated via Pip, without having to re-brew Python:

pip install --upgrade distribute

Similarly, Pip can be used to upgrade itself via:

pip install --upgrade pip

The site-packages and the PYTHONPATH.

The site-packages is a directory to contain Python modules, especially bindings installed by other formulae. Homebrew creates such a directory at $(brew --prefix)/lib/pythonX.Y/site-packages for example /usr/local/lib/python2.7/site-packages for python2.7. The reasoning is that for (minor) upgrades or reinstalls of Python, your modules are not lost. And a rather strict Homebrew policy is not to write stuff outside of the brew --prefix, so we don't spam your system.

A brewed Python 2.7 also searches for modules in

• /Library/Python/2.7/site-packages and in
• python -c "import site; print(site.USER_SITE)" => /Users/<your_name>/Library/Python/2.7/lib/python/site-packages

Homebrew's site-packages dir is first created if any Homebrew formula with Python bindings is installed or if brew install python. A brewed Python already knows about this dir.
For other Pythons you'll have to add that dir to your PYTHONPATH environment variable. You may want to append a line like so to your hidden configuration file .bash_profile in your home dir:

This is not needed if you use a brewed Python!

touch ~/.bash_profile
echo export PYTHONPATH=\"$(brew --prefix)/lib/python2.7/site-packages:\$PYTHONPATH\" >> ~/.bash_profile
source ~/.bash_profile
echo $PYTHONPATH

Homebrew provided Python bindings

Some formulae provide python bindings. Sometimes a --with-python (or similar) option has to be passed to brew install in order to build the python bindings. Check with brew options <formula>.
If you have a brewed python, then the bindings are installed for that one. But basically homebrew just uses the first python (and python-config) in your PATH. Check that by which python.

Warning, Python may crash (see Common Issues) if you import <module> in a different python interpreter than the executable that was used during the brew install <formula_with_python_bindings>. Therefore, if you decide to switch between a brewed and system python, then (re-)install all formulae that provide python bindings (such as pyside, wxwidgets, pygtk, pygobject, opencv, vtk to name just a few).

Other - non-homebrew - Python bindings

Our policy is that these should be installed via pip install <x>. To discover, you can use pip search, the new http://crate.io or http://pypi.python.org/pypi. Note, system Python does not provide pip but you can easy_install pip to fix that.

Only for brewed Python, modules installed by pip or with python setup.py, will be put into the before-mentioned $(brew --prefix)/lib/pythonX.Y/site-packages directory, too.

Further, pip (or more precisely distutils) knows which compiler flags to set in order to build bindings for software installed in Homebrew (Find the includes, the libs, the compiler and so forth).

Technical details for maintainers

Homebrew performs three actions to set up the site-packages.

• First, the Cellar site-packages folder is removed, and a symlink to /usr/local/lib/python2.7/site-packages in the prefix is created. This will allow site-packages to persist between Python updates, as Homebrew has special handling for some languages that use lib for user-installable libraries.
• Second, a distutils.cfg file is written to set the install-scripts folder to /usr/local/share/python. Users can add /usr/local/share/python to the PATH to pick up installed scripts.
• Third, a site-packes/sitecustomize.py is written in order to
  • allow other non-brewed python to parse .pth files in our site-packages
  • filter out dirs from the PYTHONPATH, starting with /System/...
  • remove the hard coded site-package location in the Cellar (where we installed Python to) so that pip uninstall works.

Standard python installers can be run as python setup.py install and the proper paths will be selected.

How to create a formula with Python bindings

todo