Ivan Voras
Ivan’s 15+ years of back-end and blockchain architecture has seen everything from DBA ops to development of OS kernel modules (FreeBSD).
Although the most wide-spread and supported way of running Django is on a Linux system (e.g., with uwsgi and nginx), it actually doesn’t take much work to get it to run on IIS. In this article, Toptal Engineer Ivan Voras walks you through a step-by-step tutorial, clearly explaining how to install Django on IIS.
Although the most wide-spread and supported way of running Django is on a Linux system (e.g., with uwsgi and nginx), it actually doesn’t take much work to get it to run on IIS. In this article, Toptal Engineer Ivan Voras walks you through a step-by-step tutorial, clearly explaining how to install Django on IIS.
Ivan’s 15+ years of back-end and blockchain architecture has seen everything from DBA ops to development of OS kernel modules (FreeBSD).
Though many Django Developers might consider it blasphemous, sometimes it is actually necessary to deploy Django applications on Windows/IIS, especially when working with a client that has based its infrastructure around the Windows ecosystem. The “blasphemy” part comes from Django having really been targeted at the Unix environment, relying heavily on features like WSGI, FastCGI, and command-line tooling, all of which are foreign to Windows. Fortunately, Django/IIS compatibility is improving, thanks to the addition of features (which would otherwise be a kludge) on both the Windows and the Python+Django sides of the equation, thereby helping to resolve compatibility issues between these two disparate technical worlds.
This short, focused tutorial walks you through the basic setup of a Django project on Windows. It covers the installation of Python, Django, and related tools, including running the Django project both standalone and as a FastCGI server. The latter is increasingly important, incidentally, since IIS now officially supports FastCGI (on IIS 7+, simply install the CGI feature).
Note: This tutorial is intended for those with a working understanding of Windows and who are familiar with the IIS management console. The version of IIS used in this tutorial is 8.5, but the descriptions and techniques are similar on earlier versions. The tutorial is based on Python 2.7 and Django 1.7, since those are the versions I use for my projects. You can find another Django tutorial here.
Pro tip: If you are going to deploy multiple Django (or even plain Python) projects, or if you are a developer, you should look at virtualenv, a tool for creating isolated Python environments.
First, download Python. Both 32-bit and 64-bit MSI installers are provided, and you should choose the one appropriate for the machine you are installing on.
It’s important that you install Python 2.7.9 or later, since Python versions beginning with 2.7.9 include PIP, the Python library/package/software manager which is used to install everything else in this tutorial.
The installer process is very straightforward and simple. It will offer to install Python in the C:\Python27
directory, which you should accept as it makes life easier afterwards. Try not to give in to the Windows habit of installing stuff in directories with spaces in their names.
The basic directory after installation will contain around 8 subdirectories, some miscellaneous files and two executables named Python.exe
and PythonW.exe
. The former is the default command-line interpreter and Python shell, while the latter is only the interpreter, which will not use (or spawn) a console window if invoked, and because of this is suitable for running GUI Python applications.
Next, Python should be added to the system’s PATH environment variable. This is done in Advanced System Settings (or System Properties), in the Advanced tab, by clicking on the Environment Variables button. There are two directories to be added: C:\Python27
and C:\Python27\Scripts
. These should be appended to the PATH list, separated by semicolons (;
). The ending of your PATH variable should look like ;C:\Python27;C:\Python27\Scripts
.
Pro tip: You may also want to install GOW, a light-weight collection of Unix command-line utilities similar to Cygwin. It will provide you with tools such as
ls
, but also more interesting ones such asmake
,wget
,curl
,ssh
,scp
,gzip
andtar
.
Django can be installed using PIP with a command such as pip install django
. The process may pull in some additional dependencies if they are not already present on your system. Otherwise, it will simply install only Django, with output similar to the following:
Downloading/unpacking django
Installing collected packages: django
Successfully installed django
Cleaning up...
You can check if both Python and Django for Windows are working by starting a new Windows Command Prompt, running the python
command, and entering the import django
command at the Python prompt. If it works properly, there should be no output or messages after the import django
command; i.e.:
Python 2.7.9 (default, Dec 10 2014, 12:24:55) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import django
>>>
A Django “project” consists of one or more “apps”. A project’s top-level directory usually contains one special project subdirectory which contains settings and some general project-level information, one subdirectory per app, and a command-line script called manage.py
. For example:
C:\Devel\djangoproject\src>dir
Volume in drive C is OS
Volume Serial Number is 6A3D-C1B8
Directory of C:\Devel\djangoproject\src
22/12/2014 04:25 <DIR> .
22/12/2014 04:25 <DIR> ..
22/12/2014 04:19 <DIR> project
22/12/2014 04:58 <DIR> djangoapp
16/12/2014 03:30 <DIR> templates
16/12/2014 00:50 250 manage.py
1 File(s) 250 bytes
5 Dir(s) 23,552,929,792 bytes free
Django projects can be simply distributed by archiving the entire project directory and decompressing it on another machine. In the example above, the project contains the project
subdirectory, the application directory named djangoapp
, and an auxiliary templates
subdirectory.
The manage.py
script is the “swiss army knife” of Django applications. It does everything from creating new apps, to database migrations, to running a test (embedded) HTTP server or even a FastCGI server.
If the project and its apps are functional, you should be able to start the default Django development-only HTTP server by running the command manage.py runserver
, which should result in output similar to the following:
C:\Devel\djangoproject\src>manage.py runserver
Performing system checks...
System check identified no issues (0 silenced).
December 23, 2014 - 01:19:02
Django version 1.7.1, using settings 'project.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.
As you can see from the messages, this starts a server on localhost, port 8000. You can access it immediately with your web browser.
A more interesting option is to enable a FastCGI server. With FastCGI, you can use IIS, Apache, or any other web server, to serve the application in a production setting. For this to work, you need to download the fcgi.py (the Django management command to run Django on Windows with IIS through FastCGI) and put it into the management/commands
subdirectory of the Django app’s (not the project’s!) subdirectory. Both the management
and the commands
subdirectories must have an empty file named __init__.py
(which turn those directories into Python modules).
fcgi.py
is a very simple and minimalistic WSGI to FastCGI adapter that does not support listening on a TCP socket or a pipe, and does all its processing by using stdin
and stdout`. As such, it is not usable with modern web servers such as nginx, but will work with IIS.
If the FastCGI module is loaded in IIS (or simply the CGI module in IIS 7+), the IIS management console will have the “FastCGI Settings” icon available. Django is a framework which has its own URL routing, so Django apps must be installed as a “handler” in IIS for specific paths. To install a Django app on the IIS’s Default Web Site, select it in the management console, and open the Handler mappings configuration feature. In it, click on the Add Module Mapping… action, and enter the following information:
\*
to handle all requests with internal Django routingFastCgiModule
to use the IIS’ FastCGI modulepython.exe
path and its command line arguments need to be set, using the pipe character (|
) as a separator. An example value for this setting is: C:\Python27\python.exe|C:\app\src\manage.py fcgi --pythonpath C:\app\src --settings project.settings
. Note that you need to specify the fcgi
command for the manage.py
script, and manually set the Python interpreter’s search path for the project, as well as the Python module name for the project’s setting module.Your configuration dialog should look something like this:
Next, click the Request restrictions button and edit the Mapping tab. Uncheck the “Invoke handler only if the request is mapped to…” checkbox (otherwise, IIS will have problems mapping what it thinks are subdirectories in the URL request):
Click OK on the handler information dialog. IIS will then ask you to confirm the creation of a matching FastCGI application entry which you will need to confirm. This entry will be visible in the FastCGI Settings feature, accessible at the root screen of the IIS Management Console. The default entry created by IIS itself is adequate, but there are some optional settings available which you may want to take advantage of:
Modern web applications use multiple resource files, such as CSS, JavaScript and others, and Django apps are no exception. Django provides for a very convenient feature which allows developers to integrate the needed resources into the application directory tree, but which can be extracted and copied by Django into a proper, static directory. This is basically a developer-controlled feature, and the locations where Django will store the static files is controlled in the project’s settings.py
. Well-behaved projects will use a reasonably sane path for this, but it is not standardized.
Apps which handle uploaded files store them in a similarly-managed directory which, in Django, is traditionally named media
. The static
and media
directories need to be added to the IIS configuration as virtual directories:
The important step here is to reconfigure the Handler Mappings feature for each of the directories and remove the Django App handler, leaving the StaticFile
handler as the most important one.
Note that the static
directory must be readable by IIS (as well as all other files and directories in the Django project), but the media
directory must also be writable by IIS. The final site configuration should resemble the following:
SQLite works by default on Windows, as it does on Unix-like systems. Most of the other open source databases now work on Windows, even PostgreSQL, which I recommend. On existing Windows installations, though, there could be a requirement to deploy Django with the MS SQL Server. This is possible either by using an ODBC bridge driver or by using a native MS SQL driver. In theory, both work, but I haven’t tested them. At least the database connection parameters (in the project’s settings.py
file) need to be changed to switch to a new database. Data migration needs to be done manually.
Note that if using the SQLite database, both the database file and the directory where it is located need to be writable by IIS.
The described configuration is tested and proven to work, but if something goes wrong, here are some basic steps for troubleshooting your Django for Windows install:
C:\inetpub\logs\FailedReqLogFiles
directory (or a similar one, depending on your configuration). You then need to enable tracing for the particular web site (or a virtual directory) in the *Configure->Failed request tracing… action.To be sure, Django is tailored for a Unix-like environment, and the most wide-spread and supported way of running Django is on a Linux system (e.g., with uwsgi and nginx).
Yet it doesn’t take much work to make Django run on Windows, as shown in this tutorial. Some of the steps described may seem counter-intuitive from a pure Windows perspective, but they are necessary and, fortunately, the effort spent in the configuration is one-time only. Once configured, the Django application should then behave in much the same way that it would on a Linux platform.
Ivan’s 15+ years of back-end and blockchain architecture has seen everything from DBA ops to development of OS kernel modules (FreeBSD).
21 years
World-class articles, delivered weekly.
World-class articles, delivered weekly.
Join the Toptal® community.