Andreas Jacobsen's Distraction

Another cause of procrastination

Using Python setuptools on the mac

Python’s standard tool for package management is setuptools. The version of setuptools bundled with Mac OS X Leopard is 0.6c7. Unfortunately, setuptools is not self-upgrading, in that it won’t replace the easy_install script in /usr/bin, and there’s no official .dmg/.pkg to upgrade it. This is important because the easy_install script that’s used to install new packages has a hardcoded version of setuptools in it, that it reads from the Python libraries bundled with Leopard.

The hardcoded version string in easy_install became a problem when I tried to install a package that relied on a newer version of setuptools:
$ sudo easy_install -U py
Searching for py
Best match: py 0.9.2
Running py-0.9.2/ -q bdist_egg --dist-dir /tmp/easy_install-PWyaOs/py-0.9.2/egg-dist-tmp-qz0KLA
The required version of setuptools (>=0.6c8) is not available, and
can't be installed while this script is running. Please install
a more recent version first, using 'easy_install -U setuptools'.

(Currently using setuptools 0.6c7 (/System/Library/Frameworks/Python.framework/Versions/2.5/Extras/lib/python))
error: Setup script exited with 2

Installing a newer version of setuptools didn’t actually help, since easy_install doesn’t get touched by this. There are two (sensible solutions) to this. Either edit /usr/bin/easy_install to reflect the newer version of the setuptools package, or use the easy_install module from python rather than the executable. The latter is preferable since it doesn’t involve manually changing stuff in /usr/bin, which is just plain wrong.

So this is how to correctly install packages that rely on a version of setuptools newer than .6c7 on a Mac:
$ sudo python -m easy_install py
Searching for py
Best match: py 0.9.2
Processing py-0.9.2-py2.5-macosx-10.5-i386.egg
Adding py 0.9.2 to easy-install.pth file
Installing py.cleanup script to /usr/local/bin
Installing py.lookup script to /usr/local/bin
Installing py.countloc script to /usr/local/bin
Installing script to /usr/local/bin
Installing py.test script to /usr/local/bin

Using /Library/Python/2.5/site-packages/py-0.9.2-py2.5-macosx-10.5-i386.egg
Processing dependencies for py
Finished processing dependencies for py

This works because python searches sys.path, and the /Library/Python site packages are placed before the bundled packages.

The state of easy_install isn’t that great. There are basically three alternatives to installing python packages. One is to use the OS package manager, which works on Linux distros like Debian/Ubuntu, where just about everything is ported to a .deb and put in the apt repositories. Unfortunately, macports doen’t have many python packages. The other is to use easy_install, warts and all. The third is to download source distros and use distutils to install them (using python install), which has a very nice retro feel to it. Fortunately, help does seem to be on the way.

Written by Andreas

October 10, 2008 at 23:00

Posted in Python

Tagged with , , ,

7 Responses

Subscribe to comments with RSS.

  1. Just use “easy_install -s /usr/bin setuptools” to upgrade the scripts in /usr/bin.

    Phillip J. Eby

    October 11, 2008 at 17:49

  2. Thanks, that looks like it’ll solve it nicely.


    October 12, 2008 at 22:51

  3. Yes, setuptools and easy_install are a major pain. I’ve switched over to using Ian Bicking’s alternative pyinstall ( for pretty much everything; it clears up a lot of the warts with easy_install, and is much easier to use in repeatable/reproducible deployments.

    Either way, you really owe it to yourself to try out virtualenv ( and virtualenvwrapper (, which have basically changed the way I work with Python — installing things into a virtualenv (with either easy_install or pyinstall, both of which work for the task) is so much simpler that I don’t think I’ll ever go back to site-wide installs and Python path hacking again :)

    James Bennett

    October 27, 2008 at 03:17

  4. Thanks for those pointers, James. Pyinstall looks quite neat. The virtualenv stuff looks interesting as well, though I dunno if it’s for my casual hacking. If I ever do anything serious with Python again I’ll definitely look at it.


    October 27, 2008 at 19:28

  5. Thanks, Andreas and Phillip! This post finally solved all those issues that have already been othering me for months now. Hooray!

    Sascha Brossmann

    December 18, 2008 at 14:23

  6. […] issue where it uses a specific version of setuptools. You can read a really good explanation by Andreas Jacobsen […]

  7. Thanks, it helped me a lot! Thank you!


    February 14, 2014 at 10:43

Comments are closed.


Get every new post delivered to your Inbox.

%d bloggers like this: