TOC()

GeoDjango Installation

Installation of GeoDjango also requires the installation of existing open source geographic libraries and a spatial database -- currently only PostGIS. This section will describe the installation process for these prerequisites. GeoDjango is best supported on Linux/UNIX platforms, but also works 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)
  • Ubuntu 7.0 (2.6 Kernel)
• 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). The ctypes module needs to be installed as well.
  • Recommended: Python 2.5 is recommended because the ctypes module comes included. ​Python 2.5.1 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 and v8.2 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
  • ​psycopg2 is a Python database adapter for PostgreSQL. Latest version is ​2.0.6.

Django

• GeoDjango exists in the gis branch from SVN:

  $ svn co http://code.djangoproject.com/svn/django/branches/gis django_gis
  $ ln -s django_gis/django /path/to/site-packages/django
  

Don't forget to use

$ python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"

to detect the correct site-packages to use.

GEOS

• We have been developing using ​GEOS 3.0.0RC4, and have not tested using GEOS 2.x. Despite the "RC" nomenclature, 3.0.0RC4 is quite stable, and will be renamed to 3.0.0 after FOSS4G.
  • See Mateusz Loskot (GEOS lead developer), ​Note about GEOS 3.0.0 release.
• GeoDjango has its own GEOS ctypes wrapper; you do not need to enable the existing GEOS Python bindings.
  • ctypes comes standard with Python 2.5. If you run Python 2.4, ctypes may be ​downloaded here
• Configure, make, and install.

  $ ./configure
  $ make
  # make install
  

• You must have g++ already installed.

PROJ.4

• Latest ​PROJ.4 version is 4.5.0. We have no reason to believe that previous versions (e.g., 4.4.x, 4.3.x) will not work.
• First, download the PROJ ​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 source. For example, if PROJ was unzipped in a directory named proj, then untar these files in proj/nad. Do this before you do the configure/make/install dance.
  • See ​PROJ FAQ; see also ​Frank Warmerdam's reply to a Mapserver question.
• Next, configure, make and install.

  $ ./configure
  $ make
  # make install 
  

PostGIS

• Required: PostGIS v1.1.0 v1.2.1 and above. 1.1.0 support is currently pending, see #5498.
• Recommended: Postgis v1.3.1 ​PostGIS (this is the ​latest version).
• On Debian etch install the flex package. (May bee its required in other Linux)

  apt_get install flex
  

• First build & install PostGIS.

  $ ./configure --with-geos --with-proj
  $ make
  # make install
  

• Next, create a role and database for your application, and allow it to access PostGIS functionality. PostGIS SQL files are installed in the PostgreSQL share directory (/usr/postgres/8.2/share in the example below -- use pg_config --sharedir to determine this directory on your system).

  # su - postgres
  $ createuser <user>
  $ createdb -O <user> <db_name>
  $ createlang plpgsql <db_name>
  $ psql -d <db_name> -f /usr/postgres/8.2/share/lwpostgis.sql
  $ psql -d <db_name> -f /usr/postgres/8.2/share/spatial_ref_sys.sql
  $ psql <db_name>
  <db_name>=# GRANT SELECT, UPDATE, INSERT, DELETE ON geometry_columns TO <user>;
  <db_name>=# GRANT SELECT ON spatial_ref_sys TO <user>;
  

• Finally, update your settings.py to reflect the name and user for the spatially enabled database. So far, we only plan to support the psycopg2 backend, thus: DATABASE_ENGINE='postgresql_psycopg2'.

GDAL

• Highly Recommended: Some features (e.g., a large number of SpatialRefSys model routines) require GDAL, but it is not necessary for core functionality like spatial queries.
• GDAL/OGR includes useful for coordinate transformations and reading/writing both vector (e.g., SHP) and raster (e.g., GeoTIFF) geographic data.
  • For example, the following command will convert your SHP file into ​WGS84 (standard lat/lon). Then you can import directly into your database using shp2pgsql (utility from PostGIS):

    ogr2ogr -t_srs WGS84 output.shp input.shp
    

• Latest ​GDAL version is 1.4.2. Configure with GEOS then make (use gmake on Solaris platforms) and install:

  $ ./configure --with-geos
  $ make
  # make install
  

• As of r5397 there's a ctypes layer for GDAL/OGR, no additional Python bindings are needed.
• If you still want to use the GDAL Python API for your own applications, then the following configuration flags:
  • --with-python --without-ngpython: the deprecated, but stable API.
  • --without-python --with-ngpython: the "next-generation" SWIG-based bindings -- used to problematic for Python 2.5 users, but the GDAL team has solved a lot of these issues in 1.4.2.
  • See generally ​GDAL/OGR In Python on the GDAL trac wiki.

Windows

Still a work in progress -- but it's a start for closing #4397.

Note: The installation for the GEOS and GDAL libaries is 'hackish' right now. A sustainable long-term solution (i.e. an installer) needs to be developed for these libraries.

Introduction

These instructions will cover using binary packages to install GeoDjango on Windows 2000/XP platforms. Compiling prerequisite packages (e.g., GEOS) from source on Windows is beyond the scope of this documentation, as it assumes the use of community-built binary installers.

That said, here are some additional program recommendations that, while not required, make your Python experience in Windows less painful:

• The Windows command-line terminal is It's difficult to re-size and copy and paste from. I (jbronn) find ​Console2 more convenient to use than one supplied with Windows (cmd.exe).
• ​IPython also runs on Windows, and makes life easier.
  • Latest version of IPython is ​0.8.1.
  • For terminal colors and tab completion (two of IPython's strong points), also install the ​pyreadline library (latest version is ​1.4.4).
  • For documentation, check out the ​IPython on Windows documentation. See also ​IPython installation windows instructions, and ​IPython on Console.

Python

Download and run the ​Python installer. We highly recommend you use Python 2.5 or greater (2.5.1 is the latest, and the version linked to). Python 2.5 includes the ctypes library, which is required for the GEOS, GDAL, and readline (if you're using IPython) interfaces. Python 2.4 users may obtain ctypes from the ​sourceforge download page.

In order to be able to invoke python from the command-line, setup your Windows Path environment variable to include the Python installation directory:

1. Right-click on "My Computer" icon (either on the Desktop or through the Start Menu).
2. Select the "Advanced" tab.
3. Click the "Environment Variables"
4. Under "System Variables" select Path and click the "Edit" button.
5. Append ";C:\Python25" to the value therein.

PostgreSQL

Download and run the PostgreSQL installer from ​here. Do not install the PostGIS version bundled with this installer. The latest version of PostgreSQL is 8.2.5.

If you want to invoke PostgreSQL commands from the shell, append ";C:\Program Files\PostgreSQL\8.2\bin" to the Windows Path.

PostGIS

PostGIS maintains a ​distribution for Windows, and includes pre-built libraries for PROJ 4.5.0 and GEOS 3.0.0rc4 (both are the latest versions). You may download the latest ​PostGIS (1.3.1) here. Run this after the PostgreSQL installer.

If you added the directory to PostgreSQL to your Path (see above), the following command may be used to easily create spatial databases:

C:\> createdb -T template_postgis <database name>

psycopg2

Windows binary packages of the psycopg2 module are packaged by Jason Erickson, and may be downloaded from his ​win-psycopg website. The latest version maintained for Python 2.5 and PostgreSQL 8.2.4 is ​pyscopg2 2.0.6.

GEOS

After PostGIS has installed, copy the GEOS (libgeos-3-0-0rc4.dll, libgeos_c-1.dll), and PROJ (libproj.dll) libraries from C:\Program Files\PostgreSQL\8.2\bin (or wherever you installed PostgreSQL) to a location accessible to the Python interpreter (e.g., C:\Python25\DLLs, or C:\Python25).

GDAL/OGR

The premiere GDAL/OGR binary package for Windows is ​FWTools, however, the libraries I downloaded (1.4.1 at the time) were missing functions needed for the library interface -- I need to investigate again to provide additional details. This is the reason why QGIS is used to obtain compiled GDAL libraries for Windows.

A snapshot (0.9.0 Preview-2) windows installer of ​Quantum GIS (QGIS) can be obtained from ​here. Once installed, copy all the DLLs from C:\Program Files\Quantum GIS to C:\Python25: Do not overwrite any dlls that come from PostGIS.

Installation Test

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

>>> from django.contrib.gis.gdal import HAS_GDAL
>>> print HAS_GDAL

>>> from django.contrib.gis.tests import test_geos
>>> test_geos.run()