How to install PostGIS and GeoDjango on Ubuntu

Note, this article was published over 3 years ago and hence the content may be stale. Consume with a pinch of salt.

Despite its extensive documentation, getting GeoDjango installed and configured can be a pain. Here are my notes for future reference:

Installation on Ubuntu 12.04

First, ensure your system locale is UTF8 as PostgreSQL uses it to determine its default encoding during installation:

$ export LANGUAGE="en_US.UTF-8"
$ export LANG="en_US.UTF-8"
$ export LC_ALL="en_US.UTF-8"

Now install dependencies:

$ sudo apt-get update
$ sudo apt-get install postgresql-server-dev-9.1 postgresql-9.1-postgis

PostgreSQL should now be installed and running with UTF8 encodings. Verify this with:

$ sudo -u postgres psql -l
                                     List of databases
       Name       |  Owner   | Encoding |   Collate   |    Ctype    |
 postgres         | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
 template0        | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
                  |          |          |             |             |
 template1        | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
                  |          |          |             |             |

Now create a spatial database. The above commands will have installed PostGIS 1.5.3 hence, according to Django's docs, we need to download and install a shell script that executes the appropriate commands:

$ wget
$ chmod +x

and run it as a privileged user:

$ sudo -u postgres ./

If this is successful, a deluge of SQL output will echo to the console. This is normal. PostGIS is now correctly installed and we have a template database we can use to create a database for our GeoDjango project.

$ sudo -u postgres psql
psql (9.1.9)
Type "help" for help.

postgres=# CREATE DATABASE sample_db TEMPLATE template_postgis;
postgres=# CREATE ROLE sample_role WITH PASSWORD 'sample_password' LOGIN;
postgres=# GRANT ALL PRIVILEGES ON DATABASE sample_db to sample_role;

This is the tricky bit over: you can now pip install psycopg2 and you're basically done. Remember to use the PostGIS database engine in your DATABASES setting:

    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',

Common errors

If your system locale is not UTF8 when attempting to create a spatial database, you'll see something like this:

$ sudo -u postgres ./
createdb: database creation failed: ERROR: encoding UTF8 does not match locale en_US
DETAIL:  The chosen LC_CTYPE setting requires encoding LATIN1
FATAL:  database "template_postgis" does not exist

If PostgreSQL is not installed when trying to install psycopg2, you see something that ends with this:

warning: manifest_maker: standard file '-c' not found

Error: pg_config executable not found.

Please add the directory containing pg_config to the PATH
or specify the full executable path with the option:

    python build_ext --pg-config /path/to/pg_config build ...

or with the pg_config option in 'setup.cfg'.

I'll add more error symptoms when I see them in the wild.