Create a gist now

Instantly share code, notes, and snippets.

Instructions on how to setup an OSX developer machine for (python/django) development

OSX Developer System installation

This guide assumes a fresh install of Mac OSX 10.7 Lion.

Brew User

Create the a User called "brew" and check "Allow user to administer this computer". Open a console as brew or switch to the brew user using sudo su - brew.


Install Xcode and the Command Line Tools from inside the Xcode Preferences. (You can use the App Store to install Xcode)


Follow to get the basic setup up and running. (the default, not the alternate installs).

Don't forget to install the requirements (Xcode, X11, Java Developer Update) mentioned in the installation guide.

Please note the recommendations below.

Dedicated brew user

Installing as root is not recommended by the homebrew authors. But I hate nothing more than accidentally installing a python package globally when I forget activating a virtualenv. To prevent this I decided to create a dedicated user called brew who has control over /usr/local/. So for everything brew related and to install global python/ruby/whatever packages it is necessary to su to brew: sudo su - brew.

python and stuff

See and for details.

the basics:

brew install python
/usr/local/bin/pip install --upgrade distribute

homebrew sets things up so that all packages installed via python install, easy_install or pip get their commands installed to /usr/local/share/python/ by default (see the above link for an explanation). So the first rule of business is to add that path to your PATH. Also if you want to use your homebrew python (and other homebrew stuff) by default, /usr/local/bin should be all the way at the front of your PATH. If you decided to make a dedicated brew user, do this for this user as well.

~/.bash_profile or ~/.profile (I recommend .profile because it works in bash and zsh:

export PATH


remember to open a new terminal or call source ~/.bash_profile in all of your open terminal windows to get PATH updated.

Before installing stuff with pip, make sure the above PATH changes worked and you are using the correct version.:

pip --version

should return something like (a path with /usr/local/):

pip 1.1 from /usr/local/lib/python2.7/site-packages/pip-1.1-py2.7.egg (python 2.7)


install some dependencies:

brew install libjpeg
brew install lcms
brew install libtiff

If you don't need FREETYPE support, the regular pip install PIL will work. There is no real need to install PIL globally then.

If you need FREETYPE, choose one of these three options. I recommend PIL with patching

PIL with patching

Since PIL is not packaged correctly, needs to be tweaked.

Use the newest source version of PIL from , download, upack and edit FREETYPE_ROOT = ("/usr/x11/lib","/usr/x11/include",) in Then:

python build_ext -i
python install

This method has the advantage, that other packages that have PIL as a dependency will detect that it is already installed.


Pillow is an alternative Distribution of PIL:

pip install Pillow

Pillow does a great job of finding all the dependencies it needs in OSX. But it sucks a bit if an other packages list PIL as a dependency, because Pillow will not be recognized as a valid PIL installation and PIL will be installed again.

PIL globally with homebrew

Homebrew has a formula for PIL:

brew install pil


This may produce the dreaded AccessInit: hash collision: 3 for both 1 and 1 error if some apps import PIL as from PIL import Image and others as import Image.

PIL compatibility

Some python packages don't work when PIL is installed with the PIL prefix. Add a PIL.pth file in /usr/local/lib/python2.7/site-packages/PIL.pth containing the string PIL. Now both from PIL import Image and import Image will work.

This oneliner will do exactly that:

echo "PIL" > /usr/local/lib/python2.7/site-packages/PIL.pth


aggdraw provides much better anti-aliasing than PIL . And lots of other stuff.

use this version:

this needs mercurial to be installed (pip install mercurial)

mkdir ~/tmp
cd ~/tmp
hg clone
cd aggdraw-64bits
/usr/local/bin/python build_ext -i
/usr/local/bin/python install

Enabling freetype does not work for me. Please share if you find a way :-)

Other graphics related stuff

brew install ghostscript
brew install imagemagick
# barcode (qrcode and others) reading lib
brew install zbar
pip install zbar



brew install mysql
# look at the instructions brew prints after installation. this is the short version:
unset TMPDIR
mysql_install_db --verbose --user=`whoami` --basedir="$(brew --prefix mysql)" --datadir=/usr/local/var/mysql --tmpdir=/tmp
mkdir -p ~/Library/LaunchAgents
cp /usr/local/Cellar/mysql/5.5.14/com.mysql.mysqld.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/com.mysql.mysqld.plist
# set a root password
/usr/local/Cellar/mysql/5.5.20/bin/mysqladmin -u root password 'new_password'


brew install mysql-connector-c

On my machine brew did not link mysql_client in /usr/local/bin, so I had to do it manually. This is probably a bug homebrew and is likely to be fixed soon.:

cd /usr/local/bin
ln -x ../Cellar/mysql/<mysql-version>/bin/mysql_config ./
pip install mysql-python



PYTHON=/usr/local/bin/python  brew install postgresql
# look at the instructions brew prints after installation. this is the short version:
initdb /usr/local/var/postgres -E utf8
mkdir -p ~/Library/LaunchAgents
cp /usr/local/Cellar/postgresql/9.1.3/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
createuser # create the initial postgres user

python client bindings (does not work without the server):

pip install psycopg2

postgis / geodjango


pip install numpy
brew install gdal
brew install postgis # this will handle installing postgres, geos, proj4, and postgis

creating a spatially-enabled database template:

createdb template_postgis # create a standard postgres db
createlang plpgsql template_postgis # enable the PL/pgSQL PostGIS functions
psql -d template_postgis -f /usr/local/Cellar/postgis/1.5.3/share/postgis/postgis.sql
psql -d template_postgis -f /usr/local/Cellar/postgis/1.5.3/share/postgis/spatial_ref_sys.sql

Creating a new database based on template_postgis:

createdb -T template_postgis [yourdatabase]

Alternatively it is possible to enable spatial functions on a existing databases by calling the above commands for creating template_postgis (except createdb, of course). Just use your existing database name instead of template_postgis.

memcached dependencies

brew install libmemcached



brew install spatialite-tools


brew install solr


brew install rabbitmq

set up a virtualhost (repeat for each app):

/usr/local/sbin/rabbitmqctl add_user myusername mypassword
/usr/local/sbin/rabbitmqctl add_vhost myvhost
/usr/local/sbin/rabbitmqctl set_permissions -p myvhost myusername ".*" ".*" ".*"

follow: (hostname)

Add correct userrole:

psql -s postgres
alter user postgres with role superuser;


brew install mongodb # look at the instructions brew prints after installation. this is the short version: cp /usr/local/Cellar/mongodb/1.8.2-x86_64/org.mongodb.mongod.plist ~/Library/LaunchAgents/ launchctl load -w ~/Library/LaunchAgents/org.mongodb.mongod.plist

Mongohub ( is an awesome OSX ui for mongodb.

gevent dependencies

gevent and related packages require libevent:

brew install libevent

Other useful tools


brew install wget

hub is a useful extension to make git github aware. gist is a commandline interface to github gists.


brew install git
brew install hub
brew install git-flow
brew install gist
brew install git-extras git-hg git-multipush git-sh git-svn-abandon git-utils

mercurial (hg):

pip install mercurial


Installation of the mercurial 2.1.1 package from pypi does not work. See for details. Until 2.1.2 is released I recommend downloading the source and running python install.


I had problems installing mercurial with pip on a 32bit MacBook Pro (Core Duo and less) because it failed to compile the 64bit version of the mercurial.base85 extension. So I downloaded the mercurial 1.8.2 package from pypi and removed -arch x86_64 near the end of and the ran python install and it worked fine.


install and make the command globally available:

brew install gettext
brew link gettext

more useful stuff

brew install ssh-copy-id
brew install vcprompt
pip install virtualenv
pip install virtualenvwrapper
brew install bash-completion
pip install ipython
pip install bpython


and virtuelenvwrapper. See for details.

pip install virtualenv
pip install virtualenvwrapper

Add this to you shell (.bash_profile or similar):

export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python
source /usr/local/share/python/

the best packagage ever

the most useful package. this one is a must.:

brew install cowsay
cowsay You can now code python on OSX. Congratulations!
gabesmed commented Apr 5, 2011

Hey guys. THANK you for this gist! I finally installed mysql-python on snow leopard without spending a whole day wanting to blow my brains out.


@gabesmed: I'm glad I prevented some bloodshed :-)


In order to enable freetype support on OS X 10.7, I had to make the following changes:

  • Set FREETYPE_ROOT correctly. I have freetype2 installed in /usr/local/include/freetype2, and the build script looks for freetype2 in <FREETYPE_ROOT>/include/freetype2. Therefore, I had to set FREETYPE_ROOT = "/usr/local" in
  • Set export CFLAGS="-fpermissive" before running build_ext -i

I had luck with the stock freetype library installed with Lion's X11 setting
FREETYPE_ROOT = "/usr/X11/"
in and then using
CFLAGS=-fpermissive python build_ext -i
CFLAGS=-fpermissive python install


Just FYI:

$ brew install vcprompt
Error: vcprompt is a head-only formula
Install with `brew install --HEAD vcprompt

Thanks for the instructions :)

aboedo commented Feb 12, 2014

great gist!! It saved me a lot of effort

mpr0xy commented Apr 27, 2015

look good for me

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment