Installing Django on OSX

Despite Django already having fairly comprehensive documentation, I still sometimes see people get confused about where the code goes, or how to get up and running quickly. Since a lot of these people are on Macs, I thought it pertinent to write all the steps down to get your own Django development environment running on OS X. Important point: this will be done entirely with native OS X tools, and won’t require you to install MacPorts or any other tools.

From this point on we’re going to be working almost exclusively in the terminal, so fire up Terminal.app (or iTerm, if you’re that way inclined).

Python and package management

OS X ships with Python already (2.5 on Leopard, 2.4 on Tiger), but it’s a slightly modified version of Python. To see which version you have, type the following in a terminal:

python

And you should see something like:

$ python
Python 2.5.1 (r251:54863, Feb  4 2008, 21:48:13) 
[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

This is actually the Python interactive shell, and you can run Python commands in here to test them out or check for installed packages. For example, we can see if Django is installed yet:

import django

Of course, if this worked successfully you wouldn’t need this article, so an error like the following should be seen:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named django

The way Python works with import is that it looks in all the directories on sys.path to find packages. Packages are diectories with __init__.py files in them (normally), or sometimes just a single Python file. For more on packages, see the Python documentation on packages.

To see which directories are looked in for packages by Python, type the following into the Python shell:

import sys
sys.path

Which should return a list (indexed mutable array) of directory paths. One of them will most likely be /Library/Python/2.5/site-packages, which is the standard Python packages directory. It’s here that most Python package managers (like easy_install) will try and put packages, but I’d normally rather keep them in somewhere which doesn’t require sudo to edit or change them. It’s a development environment after all!

Add to the Python packages

So we’re now going to add our own directory into the local version of Python. First we create a directory in our home:

mkdir ~/pythonpath

Then we need to add this directory to the PYTHONPATH environment variable:

echo "export PYTHONPATH=$HOME/pythonpath:\$PYTHONPATH" >> ~/.bash_profile
. ~/.bash_profile

PYTHONPATH is intended to extend the module search path, and in this case we will use it to add user–specific extensions to Python. We added it to your bash_profile, so it should be available whenever you open a terminal window from now on.

Now we can verify that it’s available:

python -c "import sys; print sys.path"

And your new pythonpath directory should be listed there.

Install Django

Now we need to install Django. I recommend running on the ”1.0.X” version, which is the “1.0 release with just bug fixes added” version, which is currently only available in Subversion:

svn co http://code.djangoproject.com/svn/django/branches/releases/1.0.X/django ~/pythonpath/django

which should check out the contents of 1.0.X into your pythonpath. If you don’t have Subversion installed, you can download the 1.0 tagged release as a tarball:

mkdir ~/source
cd ~/source
curl -O http://media.djangoproject.com/releases/1.0/Django-1.0.tar.gz
tar zxfv Django-1.0.tar.gz
mv Django-1.0/django ~/pythonpath/django

Which achieves the same thing as the Subversion way, except you won’t be able to update your code as new releases are tagged.

Check that Django is installed

Type the following into a command line:

python -c "import django"

No errors is a Good Thing™.

Now you have Django running, but you’ll need to get django-admin.py onto your path so that you can create new projects. You can either do:

~/pythonpath/django/bin/django-admin.py [arguments]

or get that directory onto your path. I’ll leave that as an exercise for the reader.

Now you have everything you need to run Django, but you also need a database.

Install MySQL

MySQL is by far the most straight–forward database to install, since it comes with an OS X package, so go over and install that. It should give you a nice System Preferences panel as well.

Now you need to add the MySQL commands to your path:

echo "export PATH=/usr/local/mysql/bin:$PATH" >> ~/.bash_profile
. ~/.bash_profile

And test that it works:

mysql -u root
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1
Server version: 5.0.51b MySQL Community Server (GPL)

Type ‘help;’ or ‘\h’ for help. Type ‘\c’ to clear the buffer.

mysql>

Ctrl + d exits from the client.

Update: Install MySQLdb drivers

Python doesn’t ship with a native MySQL driver, so you need to install python-mysqldb as well.

mkdir -p ~/source
cd ~/source
curl -O \
http://surfnet.dl.sourceforge.net/sourceforge/mysql-python/MySQL-python-1.2.2.tar.gz
tar zxfv MySQL-python-1.2.2.tar.gz
cd MySQL-python-1.2.2

Now there’s an issue with MySQLdb for Mac, in that there’s an error in the C code that powers it. Luckily it’s an easy fix. Edit the ~/source/MySQL-python-1.2.2/_mysql.c file, and add // to the start of the line that reads:

#define uint unsigned int

So that it instead reads:

//#define uint unsigned int

and save the file. This code was on line 38 when I last checked. Now you can build and install the extension:

python setup.py build
sudo python setup.py install

And it will be installed in your site packages. Note: I forgot this step the first time around, so thanks Kerin for reminding me.

Finished

Now you’ve done everything you need to begin the tutorials in the Django Book (with the caveat that you’ll also need to read the 0.96 to 1.0 porting guide), and in the getting started guide.

Bonus points: Python Imaging Library

In order to use the ImageField model field, you need to have the Python Imaging Library (or PIL) installed, as the images need to be validated and scaled by the model.

OS X doesn’t ship with PIL, so we need to install it ourselves.

You can download a pre–compiled version from PythonMac. This will be installed in the site-packages directory we saw earlier, and hence requires sudo on your computer (that’s what the little “you need to be authorised” popup dialogue is, more or less).

However, the installer will not run quite as planned, as it PIL on OS X installs itself in the wrong place. We need to run a few commands before we can run the freshly downloaded installer:

sudo ln -s /System/Library/Frameworks/Python.framework/ /Library/Frameworks/Python.framework
echo "export \
PYTHONPATH=/Library/Frameworks/Python.framework/Versions/2.5/lib/python2.5/\
site-packages/:\$PYTHONPATH" \
>> ~/.bash_profile
. ~/.bash_profile

Now run the installer and all should be good.

Bonus bonus points: dmigrations

If you have Subversion, and have any plans at all to update your site post–launch, you should be using dmigrations. Basically you get it onto your Python path:

svn co http://dmigrations.googlecode.com/svn/trunk/dmigrations ~/pythonpath/dmigrations

and then follow the dmigrations tutorial to get up and running. Having migrated this very site to dmigrations after launch, I can tell you that it’s much easier to just use it from the very beginning.

Note that you don’t strictly need dmigrations to develop on, but it’s something you definitely want to be thinking about before launching anything publicly using Django.

Really finished

So now you should be ready to be up and running with Django on your Mac. Happy coding!

Bradley Wright