Saturday, 22 June 2013

Running Django webapps with OS X

Django is a framework for writing python webapps. Typical instructions for installing and running Django webapps are targeted at Linux environments but as OS X is a full Unix operating system and supports the same open-source software as Linux including Python, Apache and Django it is possible to use (almost) the same Linux aimed instructions to install and run a Django webapp.

However if you want to run such a Django webapp via Apple’s software then you need to undertake some extra steps. One step that you will not need to do if you have Apple’s installed is to install mod_wsgi to allow the Apache webserver to run Django i.e. Python webapps. While the standard OS X does not include this module does.

This article will give an overview for installing a Django webapp for use with OS X but another later article will specifically show how to install the Django webapp ‘Crypt Server’. First we will look at how to install Django itself, the typical instruction for installing Django is -

sudo pip install django

However OS X as standard does not have the pip tool installed. OS X does have a similar tool called easy_install which could be used to install django but fortunately you can also use easy_install to install pip itself as follows

sudo easy_install pip

You can then use the command

sudo pip install django

You can then test it has been successfully installed and confirm what version it is using the following commands

sh-3.2# python
Python 2.7.2 (default, Oct 11 2012, 20:14:37)
[GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import django
>>> print django.get_version()
>>> quit()

After installing Django you would then download and install your webapp. We then need to setup various files so the webapp can be managed via Apple don’t really provide any documentation on how to do this (hence this article) but fortunately they do provide an example which is located at


So the first step would be to make a copy of that with a new name. The following is what that files contains.

<?xml version="1.0" encoding="UTF-7"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
 <string>Python "Hello World" app at /wsgi</string>

You then need to make the following changes, the name key needs to match the name of the copy of the above file you made, the displayName can be anything you want and is the description that will show up in, the installationIndicatorFilePath is a file it will look for to confirm your webapp is actually installed and therefore allow running it, and includeFiles is another configuration file we will look at next. You do not have to alter it but the requiredModuleNames ensures the mod_wsgi module is loaded so it can run the wsgi script i.e. the python code that makes up your webapp.

Now looking at the above mentioned includeFiles value. If you look at the file the example points to which is /Library/Server/Web/Config/apache2/httpd_wsgi.conf you will need to make your own copy of this (and updated includeFiles to match) and this is what that example contains

WSGIScriptAlias /wsgi /Library/Server/Web/Data/WebApps/hello.wsgi

This works just like a standard apache alias command and lets you point Apache to where your wsgi script is located which can be anywhere on computer and does not have to be in the standard websites folder. So you would put the full file path to your wsgi script here. This is typically somewhere in the set of folders making up your webapp. The wsgi file would be provided as part of your webapp.

Tip: If your 'wsgi' file actually came as then you need to rename it to have a wsgi file extension e.g. something.wsgi this is because Apache at least in Apple's configuration only accepts that file extension.

Presuming you have now installed Django, your webapp, and setup the above files for the final step is to create a website in which will host your webapp. This is pretty much the same process as creating a normal website but with the additional step that you click on the ‘Edit Advanced Settings…’ button in the new website and enable the entry for your webapp that should hopefully now be listed.

Note: You can also test your webapp without Apache using the command

python runserver 80

(You have to do this from the webapp directory.) This uses the lightweight webserver included with Django instead of Apache and means it also is not managed via


  1. I am having trouble getting the app to show up under the "edit advanced settings" of the server app so that I can enable it. Is there another step that is required to the the check box for my app? Great instructions btw.

    1. In order for a web app to show in you need to make your own personalised copy of with its own name, and then change the contents to point to your web app and to modify the installationIndicatorFilePath key as well.

      You also need to make your own - with your own filename copy of httpd_wsgi.conf and this needs to point to the wsgi file that runs your web app.

      With regards to getting the web app to show up just the first of these two should be needed but the second is needed to run your web app.

      If you have a look at my other article about install Crypt (a web app) here this may provide additional clarification.

    2. Thanks John, this site has been helpful.

  2. This comment has been removed by the author.

  3. This comment has been removed by the author.

  4. I'm trying to set up a Python Flask app in I have made all the changes outlined above but accessing the site returns an Internal Server Error. The Flask app runs fine from terminal. Any pointers?

    1. I have not tried doing this again under newer versions of OS X and, it is possible Apple have changed things and this would mean changes to the steps to do this. These days I use a virtualised copy of Linux perhaps running under OS X. This avoids problems being caused by Apple updates.