User Tools

Site Tools


Sidebar

Copyright © 2011

Thinkhole Labs

howto:django_on_windows

Django on Windows

Original Author: John P. Mulligan

Back in April 2006, I wrote a HOWTO for installing Django on Windows. Since that time, that guide has become quite popular and linked from various places.

On February 1, 2009 I moved the HOWTO to DokuWiki. Now, rather than posting a comment, feel free to edit, make corrections, or add helpful tips.

Sorry, but I'm getting too much spam. As of February 25, 2010, you now need to register and log in to edit howto: pages. Don't blame me. Blame the spammers. :)

Enjoy.

Step 0. Read the official documentation

There was a time when the Django documentation, while quite good, was missing quite a bit. But these days it really has just about everything you need. Your first stop should be at the official site to check out the following:

All done? Let’s move on.

Step 1. Install Python

The first step is to get the latest version of Python installed. Head on over to Python.org and download the Windows installer. Double click and run:

For the rest of this guide, the assumption is that you installed Python in C:\Python25\.

Step 2. Install PostgreSQL and Psycopg

Django supports a few different databases including PostgreSQL, MySQL, and SQLite. Personally, I’m a fan of SQLite for small projects that won’t be getting a huge amount of traffic. PostgreSQL is, however, the “recommended” database for use with Django, so we’ll use that one.

Go the PostgreSQL Downloads page (or FTP Browser) and get the latest Windows version that includes the installer.

Unpack the zip and you’ll have three files (including a README.TXT). Double click the msi file and then walk through the installer. The default options for what gets installed will probably be fine, but take a look through the options and see if there is anything else you want (e.g. PL/Java). Make sure that you have psql and pgAdmin III selected to be installed. You’ll need those:

You will be asked if you want to run Postgres as a service. If you are running Windows 2000 or Windows XP (so it’s an option) I highly recommend you say yes. It will automatically start the database and run it in the background so it’s there when you need it. You’ll need to pick a username and password for the Windows account for the service. It will create the user account for you if it doesn’t already exist.

When configuring your cluster, the default port of 5432/tcp should be fine unless you have a compelling reason to use something else. Select the proper locale (English, United States for me), and encoding (cool kids use UTF-8). You’ll also need to pick your Postgres superuser name and password. Note that this is not the same as the Windows account the service will be running as, and in fact it is not recommended to have the same password for both. I do recommend using postgres as the username, and a nice secure password:

Click through the final screens and finish. You should now have PostgreSQL installed and running as a service. To try it out, go to Start | Programs | PostgreSQL | pgAdmin III and run it. If you have Postgres running properly you should be able to double click on “PostgreSQL Database Server” and see something like the following:

To get Python to talk to the database, you’ll need Psycopg. According to the official Django docs, “version 2 is recommended with postgresql_psycopg2 backend, version 1.1 works also with the postgresql backend.”

The installation is simple, just download the installer built for Windows - (i.e. win-psycopg). Winzip or Winrar will open a tar.gz compressed file normally used on Linux/Unix. Run the installer, but make sure that you grabbed the right version! Your Psycopg version must be built to match both your Python version and your PostgreSQL version.

Step 3. Install Subversion (SVN)

Although you can always install the latest official release of Django, I’ve found that with the amount of active development going on, it’s probably a good idea to grab the latest version from SVN. That’s a lot easier than it sounds, but you will have to install Subversion for Windows to make it happen.

Go to the Subversion Downloads page and download the latest Windows installer with the basic win32 binaries. Once again, the actual installation is simple and consists of clicking through the installer steps.

Also, if you want something a little easier than the command line, you should check out TortoiseSVN. It integrates quite nicely with Windows, and I’ve been quite happy with it so far. You do not, however, need to install it.

Step 4. Install and test Django

Open a command prompt and change the directory and check out the latest revision from SVN:

C:\> cd C:\Python25\Lib\site-packages
C:\Python25\Lib\site-packages> svn co http://code.djangoproject.com/svn/django/trunk/django django

It will create a django directory and install a lot of files. Eventually it will finish with something similar to the following:

...
A C:\Python25\lib\site-packages\django\middleware\http.py
A C:\Python25\lib\site-packages\django\middleware\locale.py
A C:\Python25\lib\site-packages\django\middleware\cache.py
A C:\Python25\lib\site-packages\django\middleware\doc.py
U C:\Python25\lib\site-packages\django
Checked out revision 4714.

C:\Python25\Lib\site-packages>

Make a copy of django-admin.py (located in django\bin) and put it in C:\Python25\Scripts. That will make it easier to run in the future. Also, see the note at the end of this guide for tips on setting your Path environment variable.

Congrats, Django is now installed on your system!

By the way, if you ever want to update your Django source to the latest revision, just cd into your django directory and run svn update from there:

C:\Python25\Lib\site-packages>cd django
C:\Python25\Lib\site-packages\django>svn update
U core\management.py
Updated to revision 4716.

At this point, it would probably be a good idea to make sure that your Django install works before you attempt to get it working with Apache and mod_python. So let’s use the tutorial to create a basic Django project and test the setup:

C:\Documents and Settings\John>cd C:\
C:\>mkdir django
C:\>cd django
C:\django>django-admin.py startproject testproject
C:\django>cd testproject
C:\django\testproject>python manage.py runserver
Validating models...
0 errors found.

Django version 0.96-pre, using settings 'testproject.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.
[12/Mar/2007 20:45:50] “GET / HTTP/1.1″ 404 2063

Assuming you didn’t get any errors, you should be able to open your browser and confirm that it works:

Step 5. Install Apache and mod_python

Next up is Apache…

While Django does come with an extremely handy development server that you can use for coding and testing apps, you’ll eventually want to be able to push your application into production. So it’s probably a good idea to get a real Apache install up and running that you can play with.

Installing Apache 2.x on Windows wasn’t nearly as difficult as I thought it would be. Basically head on over to the Apache site and grab the latest win32 binaries.

Double click and run the installer. If you get errors saying that the Installation Wizard was interrupted, check out my post about that.

You will need to enter some information about your system. Your network name will generally be your domain (e.g. thinkhole.org). Your server name will probably either be localhost if you only want local access, or your full hostname if you want to be able to access it over the net (e.g. serpent.thinkhole.org). Enter an email address for the administrator and select the option to install for all users on port 80.

Note that if you choose to run Apache on port 8000, it will conflict with the default port for the Django development/test server. Not cool.

Now test to see if Apache is up and running. Point your favorite browser at http://localhost (or 127.0.0.1) and see what happens. If you a see a page similar to the following, you are all set:

A nice feature of Apache on Windows (did I just say that?!) is the Apache Service Monitor that you can access via the icon in the bottom-right of your screen. Just click on it and it will come up. From there you can stop, start, and restart the server:

Quite handy.

Now that Apache is working, it’s time to install http://www.modpython.org/mod_python. Download the win32 binaries that match both your Python version and your Apache version. Double click the installer and follow the instructions in the Wizard:

Note that when it asks you for where Apache is installed, in most cases that will be here:

C:\Program Files\Apache Software Foundation\Apache2.2\

After the installer finishes, you still have one more thing to do. Open your Apache configuration file, usually located at C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf with notepad. Scroll down and look for a section that includes a bunch of lines that start with LoadModule. Add the following line to that section:

LoadModule python_module modules/mod_python.so

Save the file and close it. Open up the Apache Service Monitor and click Restart. You should see the following text:

The Apache2 service is restarting.
The Apache2 service has restarted.

If you get errors, you probably made a typo in the configuration file when you were editing it. Check it and try again. If you don’t have any errors, you should be all set.

Step 6. Configure Apache for Django

Now that everything is installed and we know that Django is working properly, it’s time to get it working with Apache and mod_python.

Open your Apache2 config file located at C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf and add the following to the bottom of the file:

  <Location "/testproject/">
  SetHandler python-program
  PythonHandler django.core.handlers.modpython
  SetEnv DJANGO_SETTINGS_MODULE testproject.settings
  PythonOption django.root /testproject
  PythonDebug On
  PythonPath "['/django'] + sys.path"
  </Location>
  MaxRequestsPerChild 1
  if you have problems, try adding the python and document-root enviroment to 'PythonPath':
  <Location "/testproject/">
  SetHandler python-program
  PythonHandler django.core.handlers.modpython
  SetEnv DJANGO_SETTINGS_MODULE testproject.settings
  PythonOption django.root /testproject
  PythonDebug On
  PythonPath "['c:/Python25','c:/wamp/www/testproject', 'c:/wamp/www', '/django'] + sys.path"
  </Location>

add this line in your httpd.conf file to force Apache to reload everything for each request. But don't do that on a production server, or we'll revoke your Django privileges. (source)

VirtualHosts If already have VirtualHosts and like to add a certain URL to a Django Project, you can add instead these lines to your httpd.conf

<VirtualHost *:80>
  ServerName www.yourdomain.dev
  DocumentRoot "c:/wamp/www/testproject/"
 
  # Serve django pages
  <LocationMatch ^/(.*)$>
    SetHandler mod_python
    PythonHandler django.core.handlers.modpython
    SetEnv DJANGO_SETTINGS_MODULE settings
    PythonOption django.root
    PythonAutoReload Off
    PythonDebug On
    PythonPath "['c:/Python25','c:/wamp/www/testproject', 'c:/wamp/www', '/django'] + sys.path"
  </LocationMatch>
 
  # Serve static media without running it through mod_python (overrides the above)
  <LocationMatch ^(/(media|css|images|scripts|errordocs))>
    SetHandler None
  </LocationMatch>
  
</VirtualHost>

Make sure you restart Apache after making the changes to httpd.conf.

Assuming there were no errors in any of the steps up to this point, you should now be able to browse to http://localhost/testproject/ and be greeted with this page:

If that’s what you see, then you have Django installed and running via Apache and mod_python, ready for anything you can throw at it. Congrats!

Troubleshooting/Notes

  • You might need to adjust your PATH environment variable to make all of this work. To do so, right click My Computer and hit Properties. Go the Advanced tab and click on Environment Variables. Select the Path system variable (NOT user variable) from the list and click Edit. Make sure that all of the following are included in your path (i.e. Variable value), separated by semicolons: C:\Python25\Scripts;C:\Python25;C:\Program Files\Subversion\bin;
  • If you get an error complaining about being unable to find django specific modules, the easiest way to fix this is to create a new environment variable called PYTHONPATH (or modify the existing variable) and put the path to django in it. If installing using SVN, double-check to that django install is under the Python directory (something like this: C:\Python25\Lib\site-packages\django).
  • Some people seem to use C:\Python25\tools instead of “scripts”… seems odd to me, but if that’s the case, you’ll need to adjust your path accordingly. That should fix most “command not found” type errors.
  • Note that if you alter your path while you have a cmd.exe console open, you must restart the console before the changes will take effect.
  • The django.root directory does not point to your Django installation directory. It should be set to the same string as in the Location directive. The effect of this is that Django will automatically strip the /testproject string from the front of any URLs before matching them against your URLconf patterns.
  • On Vista, if you cannot seem to edit & save httpd.conf on Apache root directory, did you turn off UAC? Are you logged in as administrator? After Apache and PHP have been installed correctly and UAC has been turned back on, you can edit httpd.conf by going to the Start menu and right-clicking Notepad. Select Run as administrator. When Notepad opens, you can go to File > Open, select All files in the Type drop-down menu, and navigate to httpd.conf. Because Notepad is running as administrator, you should have no problem saving the file after editing.

Getting Django to work with Vista

(Dave Smith) I didn't have to do this on my Vista ThinkPad. The two argument version seems to work correctly “out of the box”.

If you get Type 'django-admin.py help' for usage. when trying to run django-admin.py startproject mysite, the cause of the problem is that only the first argument (startproject) gets transferred to django-admin.py. This seems to be a Vista feature, and furthermore, Vista itself has no tools to fix the situation. However, the following works:

  1. Download and install Creative Element Power Tools (not free, 45 day trial).
  2. Open it.
  3. Turn on the Edit file type associations option, and click Accept.
  4. Right-click on any .py file, and select Edit File Type. Set the “application” to C:\Python26\python.exe or something similar, and (this is the critical part) ”%1” %* to the command-line arguments.

Now it should work!

howto/django_on_windows.txt · Last modified: 2011/01/01 18:27 by john