Version 34 (modified by jbronn, 17 years ago) ( diff )

Added GDAL installation troubleshooting tip about GDAL_DATA environment variable.

TOC()

GeoDjango Installation

Installation of GeoDjango also requires the installation of existing open source geographic libraries and a spatial database -- currently only PostGIS, Oracle Spatial/Locator, and MySQL are supported. This section will describe the installation process for these prerequisites. GeoDjango is best supported using 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)
    • Ubuntu 7.0 (2.6 Kernel)
    • Centos 5 (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). 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

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

To detect the correct site-packages directory, the following command may be used: 

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

GEOS

  • 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 http://geos.refractions.net/downloads/geos-3.0.0.tar.bz2
$ 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

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

PROJ.4

  • 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 (​mirror site) 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 ftp://ftp.remotesensing.org/proj/proj-4.6.0.tar.gz
$ 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 ftp://ftp.remotesensing.org/proj/proj-datumgrid-1.3.tar.gz
$ 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: 

$ ./configure
$ make
# make install

PostGIS

First, download PostGIS, and untar the archive: 

$ wget http://postgis.refractions.net/download/postgis-1.3.2.tar.gz
$ tar xzf postgis-1.3.2.tar.gz
$ cd postgis-1.3.2

Run the configure script enabling GEOS and PROJ support, make, and install. 

$ ./configure --with-geos --with-proj
$ 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. PostGIS SQL files are 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). 

# 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>;
  • Note: if you experience errors about not finding libraries, you may need to adjust your LD_LIBRARY_PATH (which may be configured system-wide by editing /etc/ld.so.conf and running ldconfig)(Hint: Most of the times the libraries you are looking for are in '/usr/local/lib'). 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 settings.py to reflect the name and user for the spatially enabled database (thus far, we only plan to support the psycopg2 backend for PostgreSQL): 

DATABASE_ENGINE='postgresql_psycopg2'
DATABASE_NAME='<db_name>'
DATABASE_USER='<user>'

GDAL

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

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.0), and untar the archive: 

$ wget http://download.osgeo.org/gdal/gdal-1.5.0.tar.gz
$ tar xzf gdal-1.5.0.tar.gz
$ cd gdal-1.5.0

Configure with GEOS support, run make (use gmake on Solaris platforms) and install: 

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

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 manage.py shell

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 and OSR 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.

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:

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) 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).

Note: The path to the GEOS library may be manually specified by setting GEOS_LIBRARY_PATH in your settings with the full path of the DLL.

PROJ.4

Download the ​PROJ 4.6.0 Windows binary distribution and extract to a location on your hard drive (for example C:\PROJ). Copy the PROJ DLL, proj.dll, from your extraction location to C:\Python25. Finally, create a Windows environment variable (see above for instructions) entitled PROJ_LIB and have it set to the nad subdirectory where you extracted the PROJ distribution (e.g., C:\PROJ\nad).

GDAL

Download the ​GDAL 1.5 Windows binary distribution and extract to a location on your hard drive (for example C:\gdalwin32-1.5). Copy all the DLLs from the bin subdirectory of the extraction location to C:\Python25. Finally, create another Windows environment variable called GDAL_DATA, setting it to the data subdirectory where the GDAL distribution was extracted (e.g., C:\gdalwin32-1.5\data).

Note: The path to the GDAL library may be manually specified by setting GDAL_LIBRARY_PATH in your settings with the full path of the DLL.

Oracle

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.

Requirements

  • 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
True
>>> from django.contrib.gis.tests import test_gdal
>>> test_gdal.run()

>>> from django.contrib.gis.tests import test_geos
>>> test_geos.run()
Note: See TracWiki for help on using the wiki.
Back to Top