Version 70 (modified by jbronn, 11 years ago) (diff)

Point Windows documentation to instructions and installer at


GeoDjango Installation

GeoDjango requires the installation of several open source geographic libraries and a database system with spatial extensions

  • Currently PostgreSQL (with PostGIS), MySQL, and Oracle (Spatial/Locator) are supported.
  • PostgreSQL is the recommended database, having the most mature and feature-rich spatial functions and operators.
  • Note: Several components of GeoDjango can be used without a database (ie. The GeoIP utility)
  • GeoDjangoDebianLennyInstall : No compilation required, all the Debian packages work with geodjango out of the box.

This section will describe the source code installation process for these prerequisites.


GeoDjango is best supported using PostgreSQL/PostGIS on Linux/UNIX platforms, but will also run on Windows (with a little more effort). The following platforms have been confirmed to work -- feel free to add to the list:

  • Linux
    • Debian Woody (2.4 Kernel)
    • Debian etch (2.6 Kernel)
    • Debian Lenny? (2.6 Kernel)
    • Ubuntu Hardy Heron 8.04 (2.6 Kernel)
    • Ubuntu 7.0 (2.6 Kernel)
    • Centos 5 (2.6 Kernel)
    • White Box Enterprise Linux 3.0 (2.4 Kernel)
    • openSUSE 10.2 (2.6 Kernel)
    • Archlinux (2.6 Kernel)
    • Fedora 9 (2.6 Kernel)
  • Mac OS X
    • 10.4.10 (Tiger)
    • 10.5 (Leopard)
  • Solaris 5.11
  • Windows XP SP2

Linux & UNIX Platforms

Python & PostgreSQL

  • Python
    • Required: Python 2.4 is required because of heavy use of 2.4 decorator syntax (e.g. @property).
      • If using Python 2.4, the ctypes module needs to be installed as well.
      • Binary packages like python2.4-ctypes on Ubuntu/Debian may be used; however, older distributions (like Ubuntu 6.06) use old versions of ctypes that contain bugs -- in such instances, install the latest version (currently 1.0.2) which may be obtained from the ctypes sourceforge project.
    • Recommended: Python 2.5 is recommended because the ctypes module comes included. Python 2.5.2 is the current latest.
  • PostgreSQL
    • Recommended: PostgreSQL 8.x. If installing binary packages, please install the development package as well for headers required in PostGIS compilation.
    • We are currently developing using both v8.1-8.3 of PostgreSQL.
    • On Ubuntu Feisty and Debian etch, install postgresql-8.x and postgresql-server-dev-8.x (the development package is required for PostGIS compilation).
      • On Debian etch install the libpq-dev package, which includes the pg_config executable (also required for PostGIS compilation).
  • psycopg2


GeoDjango was merged into SVN trunk as of r8219. Follow Django's development version installation instructions.


  • Required: GEOS v3.0.0RC4 and above (not compatible with the 2.x versions).
  • Recommended: GEOS 3.0.0 (support for the release candidate versions will be eventually deprecated due to differences in the way geometries are serialized to WKT and HEX, as well as compilation issues for OSX 10.5 -- we urge users to migrate to 3.0.0).

GEOS is an open source C++ library for performing geometric operations, and powers GeoDjango's "lazy" geometries.

GeoDjango has its own GEOS ctypes wrapper; you do not need to enable the existing GEOS Python bindings. The ctypes library comes standard with Python 2.5; if you run Python 2.4, ctypes may be downloaded here, and in Debian etch you may install the python-ctypes package.

First, download GEOS 3.0.0 from the refractions website and untar the source archive:

$ wget
$ tar xjf geos-3.0.0.tar.bz2

Next, change into the directory where GEOS was unpacked, run the configure script, compile, and install:

$ cd geos-3.0.0
$ ./configure
$ make
# make install

Troubleshooting: The libgeos is a dependency of both GeoDjango directly and PostGIS. If you get errors like Could not find the GEOS library (tried "geos_c") during syncdb or when loading the postgis functions into your database (see below), then the library is either not installed or properly linked.

  • You should first make sure that the directory which the GEOS C library was installed in is properly linked.
    • This location is usually usr/local/lib on unix systems and can be linked on linux by confirming that /usr/local/lib is within /etc/ and then running:
      $ ldconfig
    • It can also be set as an env variable on Linux by placing export LD_LIBRARY_PATH=/usr/local/lib in your bash_profile.
    • It can be set as an env variable on Mac by placing export DYLD_LIBRARY_PATH=/usr/local/lib in your bash_profile.
  • As a backup option, the path to the GEOS library may be manually specified by setting GEOS_LIBRARY_PATH in your with the full path to the GEOS library (e.g., /path/to/ for linux or /path/to/libgeos_c.dylib file for mac).
  • Note: If the error occured during postgis function insert then restart the PostgreSQL server after making these changes.


  • Required: 4.5.0 -- this is not a strict requirement, GeoDjango has been tested with 4.5.0, but there is no reason to believe that previous versions (e.g., 4.4.x, 4.3.x) will not work.
  • Recommended: 4.6.0 (the current latest).

PROJ.4 is a library for converting geospatial data to different coordinate reference systems.

First, download PROJ.4 from the remotesensing website, and untar the source archive:

$ wget
$ tar xzf proj-4.6.0.tar.gz

Next, download the PROJ.4 datum shifting files. These will come in handy for coordinate transformations when other programs (like Mapserver or Mapnik) are not able to cope with EPSG transformations (I learned the hard way). Untar/unzip these in the nad subdirectory of the PROJ.4 source:

$ wget
$ cd proj-4.6.0/nad
$ tar xzf ../../proj-datumgrid-1.3.tar.gz

Do this before you do the configure/make/install dance.

Finally, configure, make and install PROJ.4 within the proj-4.6.0 directory:

$ cd ../
$ ./configure
$ make
# make install 


For source install first download PostGIS, and untar the archive:

$ wget
$ tar xzf postgis-1.3.3.tar.gz
$ cd postgis-1.3.3

Run the configure script, make, and install steps.

$ ./configure
$ make
# make install
  • Note: the flex package maybe required for PostGIS compilation on Debian distributions and may be installed with the command: apt-get install flex

Next, create a role and database for your application, and allow it to access PostGIS functionality.

Start by switching into the postgres user(see below about db initialization if you don't have a postgres user)

# su - postgres

As the postgres user (the user who initialized the database cluster) now do:

$ createuser <user>
  • Note: if you have not initialized the postgres db cluster (if you used apt-get to install postgresql this was already done) do this:
    sudo adduser postgres
    # run through interactive prompt
    sudo su - postgres
    mkdir /path/to/postgres/data
    chmod -R 700 /path/to/postgres/data
    initdb -D /path/to/postgres/data
    pg_ctl start -D /path/to/postgres/data

If you get any errors see

Now, create the database with your chosen user:

$ createdb -O <user> <db_name>
$ createlang plpgsql <db_name>

Now, load the postgis sql functions and spatial_ref_table of projection information.

Note: PostGIS SQL files are ususally installed in the PostgreSQL share directory (/usr/postgres/8.2/share in the example below). Use the pg_config --sharedir command to determine this directory on your system, which can vary widely depending on your PostgreSQL version and install method.

In addition, depending on your install method for postgis the sql files may be in another location like `/usr/share'.

$ psql -d <db_name> -f /usr/postgres/8.2/share/lwpostgis.sql # check your PostgreSQL Version, 8.x

If the lwpostgis.sql file is not found try:

$ psql -d <db_name> -f /usr/share/lwpostgis.sql # another possible installation location

Note: ignore any NOTICES, like 'psql:/usr/share/lwpostgis.sql:44: NOTICE: type "histogram2d" is not yet defined'

Note: errors like ERROR: could NOT access file "$libdir/liblwgeom": No such file OR directory see troubleshooting below

$ psql -d <db_name> -f /usr/postgres/8.2/share/spatial_ref_sys.sql
$ psql <db_name>
<db_name>=# ALTER TABLE geometry_columns OWNER TO <user>;
<db_name>=# ALTER TABLE spatial_ref_sys OWNER TO <user>;
  • Troubleshooting: if you experience errors about not finding libraries, you should confirm that (.dylib on mac) has been properly installed and linked prior to configuring PostGIS. Otherwise you will need to rebuild PostGIS. If it was built and installed properly you may need to adjust your LD_LIBRARY_PATH, or DYLD_LIBRARY_PATH (on mac). (This environment can also be configured system-wide on linux by editing /etc/ and running ldconfig)
    • Hint: Most of the time the libraries you are looking for are in '/usr/local/lib', but geos in particular will output its install location during the make install step.
    • Sometimes the errors are too many and not descriptive (i.e. operation aborted), in that cases use the '-s' switch on psql to debug step by step. On Solaris platforms use the crle utility to configure the runtime linking environment.

Finally, update your to reflect the name and user for the spatially enabled database (thus far, we only plan to support the psycopg2 backend for PostgreSQL):


Connection Troubleshooting: For Django to have proper access to your postgres database you may also need to configure the pg_hba.conf file. Read more about it here:


  • Required: GDAL versions 1.4.0 and above (GeoDjango has not been tested with the 1.3.x series).
  • Recommended: GDAL version 1.5.x and above.

GDAL/OGR is an excellent open source geospatial library that support features such as coordinate transformations and reading/writing both vector (e.g., SHP) and raster (e.g., GeoTIFF) geographic data -- however, GeoDjango does not yet support GDAL's raster capabilities. Installation of GDAL is highly recommended because some features (e.g., a large number of SpatialRefSys model routines and the LayerMapping utility) require GDAL capabilities; however GDAL is not required for core functionality like spatial queries. First, download the latest GDAL version (currently 1.5.2), and untar the archive:

$ wget
$ tar xzf gdal-1.5.2.tar.gz
$ cd gdal-1.5.2

Configure specifying the data directory (if installing in /usr/local, then use /usr/local/share/gdal), run make (use gmake on Solaris platforms) and install:

$ ./configure --datadir=/usr/local/share/gdal
$ make
# make install
  • Specifying the data directory at compile time avoids having to set the GDAL_DATA environment variable (see GDAL ticket #2382 and the troubleshooting tip below).

GDAL Troubleshooting

First try:

  • Make sure /usr/local/lib is in /etc/
  • Run $ ldconfig
  • Log out and back into your shell to make sure your settings have taken effect

Further Troubleshooting: If you receiving the following error message when running the GDAL tests and/or working with SpatialReference objects:

ERROR 4: Unable to open EPSG support file gcs.csv.
OGRException: OGR failure.

The solution is to set the GDAL_DATA environment variable to the location of the GDAL data files (typically /usr/local/share; use the gdal-config --datadir command to find out for sure) before invoking Python. For example:

$ export GDAL_DATA=`gdal-config --datadir`
$ python shell

You may need to add this environment variable to your Apache configuration file (sites-available/default for example):

SetEnv GDAL_DATA /usr/local/share

Note: The path to the GDAL library may be manually specified by setting GDAL_LIBRARY_PATH in your settings with the full path to the GDAL library (e.g., the .so or .dylib file).

Because GeoDjango uses a native ctypes API to access OGR (Vector shape library) and OSR (Spatial reference library) capabilities, there is no need configure the GDAL Python bindings. If you still want to use the GDAL Python API for your own applications, then use the following configuration flags:

  • --with-python: Enables the GDAL Python bindings (all GDAL modules in osgeo namespace)
  • --with-ogpython: The "old-generation" bindings (separate modules, e.g., ogr and osr)
  • See generally GDAL/OGR In Python on the GDAL trac wiki.


Please refer to Windows installation instructions available at


GeoDjango has preliminary support for Oracle Locator/Spatial as of r6524 (though none of the advanced features of Oracle Spatial are utilized). Oracle's express edition (XE) is not supported. Apparently, even though XE supports Locator's SDO_GEOMETRY objects and queries, XE does not include support for Java extensions -- which are required to construct and/or extract geometries from WKT. For the sake of simplicity, WKT geometry construction and extraction was used when implementing the [browser:django/branches/gis/django/contrib/gis/db/backend/oracle Oracle spatial backend]. Patches for creating WKT from SDO_GEOMETRY statements would be required to extend support for the XE platforms.


  • Oracle 10g and above with Locator (installation is way beyond the scope of this documentation).
  • cx_Oracle 4.3.2 and above.
  • GEOS (still required for Lazy-Geometries -- see installation instructions above).

Third-Party Library Installation Tests

You can run these tests in order to see if the installation was successful.

$ python
>>> from django.contrib.gis.gdal import HAS_GDAL
>>> print HAS_GDAL # Will be False if GDAL libraries are not found
>>> from django.contrib.gis.tests import test_gdal

If HAS_GDAL == FALSE, see GDALTroubleshooting

>>> from django.contrib.gis.tests import test_geos
Back to Top