<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>GeoDjango Installation — Django v1.2 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '1.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<link rel="top" title="Django v1.2 documentation" href="../../../index.html" />
<link rel="up" title="GeoDjango" href="index.html" />
<link rel="next" title="GeoDjango Model API" href="model-api.html" />
<link rel="prev" title="GeoDjango Tutorial" href="tutorial.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django v1.2 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../index.html">Home</a> |
<a title="Table of contents" href="../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../genindex.html">Index</a> |
<a title="Module index" href="../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="tutorial.html" title="GeoDjango Tutorial">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="model-api.html" title="GeoDjango Model API">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-gis-install">
<div class="section" id="s-geodjango-installation">
<span id="s-ref-gis-install"></span><span id="geodjango-installation"></span><span id="ref-gis-install"></span><h1>GeoDjango Installation<a class="headerlink" href="#geodjango-installation" title="Permalink to this headline">¶</a></h1>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>In general, GeoDjango installation requires:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#python24"><em>Python 2.4+</em></a> and <a class="reference internal" href="#django"><em>Django</em></a></li>
<li><a class="reference internal" href="#spatial-database"><em>Spatial Database</em></a></li>
<li><a class="reference internal" href="#geospatial-libs"><em>Geospatial Libraries</em></a></li>
</ol>
<p>Details for each of the requirements and installation instructions
are provided in the sections below. In addition, platform-specific
instructions are available for:</p>
<ul class="simple">
<li><a class="reference internal" href="#macosx"><em>Mac OS X</em></a></li>
<li><a class="reference internal" href="#ubuntudebian"><em>Ubuntu & Debian GNU/Linux</em></a></li>
<li><a class="reference internal" href="#windows"><em>Windows XP</em></a></li>
</ul>
<div class="admonition-use-the-source admonition ">
<p class="first admonition-title">Use the Source</p>
<p class="last">Because GeoDjango takes advantage of the latest in the open source geospatial
software technology, recent versions of the libraries are necessary.
If binary packages aren’t available for your platform,
<a class="reference internal" href="#build-from-source"><em>installation from source</em></a>
may be required. When compiling the libraries from source, please follow the
directions closely, especially if you’re a beginner.</p>
</div>
</div>
<div class="section" id="s-requirements">
<span id="requirements"></span><h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-python-2-4">
<span id="s-python24"></span><span id="python-2-4"></span><span id="python24"></span><h3>Python 2.4+<a class="headerlink" href="#python-2-4" title="Permalink to this headline">¶</a></h3>
<p>Because of heavy use of the decorator syntax, Python 2.4 is minimum
version supported by GeoDjango. Python 2.5+ is recommended because the
<a class="reference external" href="http://docs.python.org/lib/module-ctypes.html">ctypes</a> module comes included; otherwise, 2.4 users will need to
<a class="reference external" href="http://sourceforge.net/projects/ctypes/files/">download and install ctypes</a>.</p>
</div>
<div class="section" id="s-django">
<span id="s-id3"></span><span id="django"></span><span id="id3"></span><h3>Django<a class="headerlink" href="#django" title="Permalink to this headline">¶</a></h3>
<p>Because GeoDjango is included with Django, please refer to Django’s
<a class="reference internal" href="../../../intro/install.html"><em>installation instructions</em></a> for details on how to install.</p>
</div>
<div class="section" id="s-spatial-database">
<span id="s-id4"></span><span id="spatial-database"></span><span id="id4"></span><h3>Spatial Database<a class="headerlink" href="#spatial-database" title="Permalink to this headline">¶</a></h3>
<p>PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
the spatial databases currently supported.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">PostGIS is recommended, because it is the most mature and feature-rich
open source spatial database.</p>
</div>
<p>The geospatial libraries required for a GeoDjango installation depends
on the spatial database used. The following lists the library requirements,
supported versions, and any notes for each of the supported database backends:</p>
<table class="docutils">
<colgroup>
<col width="15%" />
<col width="24%" />
<col width="15%" />
<col width="47%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Database</th>
<th class="head">Library Requirements</th>
<th class="head">Supported Versions</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>PostgreSQL</td>
<td>GEOS, PROJ.4, PostGIS</td>
<td>8.1+</td>
<td>Requires PostGIS.</td>
</tr>
<tr><td>MySQL</td>
<td>GEOS</td>
<td>5.x</td>
<td>Not OGC-compliant; limited functionality.</td>
</tr>
<tr><td>Oracle</td>
<td>GEOS</td>
<td>10.2, 11</td>
<td>XE not supported; not tested with 9.</td>
</tr>
<tr><td>SQLite</td>
<td>GEOS, GDAL, PROJ.4, SpatiaLite</td>
<td>3.6.+</td>
<td>Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-geospatial-libraries">
<span id="s-geospatial-libs"></span><span id="geospatial-libraries"></span><span id="geospatial-libs"></span><h3>Geospatial Libraries<a class="headerlink" href="#geospatial-libraries" title="Permalink to this headline">¶</a></h3>
<p>GeoDjango uses and/or provides interfaces for the the following open source
geospatial libraries:</p>
<table class="docutils">
<colgroup>
<col width="20%" />
<col width="31%" />
<col width="27%" />
<col width="22%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Program</th>
<th class="head">Description</th>
<th class="head">Required</th>
<th class="head">Supported Versions</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><a class="reference internal" href="geos.html#ref-geos"><em>GEOS</em></a></td>
<td>Geometry Engine Open Source</td>
<td>Yes</td>
<td>3.2, 3.1, 3.0</td>
</tr>
<tr><td><a class="reference external" href="http://trac.osgeo.org/proj/">PROJ.4</a></td>
<td>Cartographic Projections library</td>
<td>Yes (PostgreSQL and SQLite only)</td>
<td>4.7, 4.6, 4.5, 4.4</td>
</tr>
<tr><td><a class="reference internal" href="gdal.html#ref-gdal"><em>GDAL</em></a></td>
<td>Geospatial Data Abstraction Library</td>
<td>No (but, required for SQLite)</td>
<td>1.7, 1.6, 1.5, 1.4</td>
</tr>
<tr><td><a class="reference internal" href="geoip.html#ref-geoip"><em>GeoIP</em></a></td>
<td>IP-based geolocation library</td>
<td>No</td>
<td>1.4</td>
</tr>
<tr><td><a class="reference external" href="http://postgis.refractions.net/">PostGIS</a></td>
<td>Spatial extensions for PostgreSQL</td>
<td>Yes (PostgreSQL only)</td>
<td>1.5, 1.4, 1.3</td>
</tr>
<tr><td><a class="reference external" href="http://www.gaia-gis.it/spatialite/index.html">SpatiaLite</a></td>
<td>Spatial extensions for SQLite</td>
<td>Yes (SQLite only)</td>
<td>2.4, 2.3</td>
</tr>
</tbody>
</table>
<div class="admonition-install-gdal admonition ">
<p class="first admonition-title">Install GDAL</p>
<p class="last">While <a class="reference internal" href="#gdalbuild"><em>GDAL</em></a> is technically not required, it is <em>recommended</em>.
Some features of GeoDjango (including the <a class="reference internal" href="layermapping.html#ref-layermapping"><em>LayerMapping data import utility</em></a> and the geographic
admin) depend on its functionality.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
independently of Django. In other words, no database or settings file
required – just import them as normal from <a class="reference internal" href="index.html#module-django.contrib.gis" title="django.contrib.gis: Geographic Information System (GIS) extensions for Django"><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.gis</span></tt></a>.</p>
</div>
</div>
</div>
<div class="section" id="s-building-from-source">
<span id="s-build-from-source"></span><span id="building-from-source"></span><span id="build-from-source"></span><h2>Building from Source<a class="headerlink" href="#building-from-source" title="Permalink to this headline">¶</a></h2>
<p>When installing from source on UNIX and GNU/Linux systems, please follow
the installation instructions carefully, and install the libraries in the
given order. If using MySQL or Oracle as the spatial database, only GEOS
is required.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>On Linux platforms, it may be necessarry to run the <tt class="docutils literal"><span class="pre">ldconfig</span></tt>
command after installing each library. For example:</p>
<div class="last highlight-python"><pre>$ sudo make install
$ sudo ldconfig</pre>
</div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">OS X users are required to install <a class="reference external" href="http://developer.apple.com/tools/xcode/">Apple Developer Tools</a> in order
to compile software from source. This is typically included on your
OS X installation DVDs.</p>
</div>
<div class="section" id="s-geos">
<span id="s-geosbuild"></span><span id="geos"></span><span id="geosbuild"></span><h3>GEOS<a class="headerlink" href="#geos" title="Permalink to this headline">¶</a></h3>
<p>GEOS is a C++ library for performing geometric operations, and is the default
internal geometry representation used by GeoDjango (it's behind the "lazy"
geometries). Specifically, the C API library is called (e.g., <tt class="docutils literal"><span class="pre">libgeos_c.so</span></tt>)
directly from Python using ctypes.</p>
<p>First, download GEOS 3.2 from the refractions website and untar the source
archive:</p>
<div class="highlight-python"><pre>$ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2
$ tar xjf geos-3.2.2.tar.bz2</pre>
</div>
<p>Next, change into the directory where GEOS was unpacked, run the configure
script, compile, and install:</p>
<div class="highlight-python"><pre>$ cd geos-3.2.2
$ ./configure
$ make
$ sudo make install
$ cd ..</pre>
</div>
<div class="section" id="s-troubleshooting">
<span id="troubleshooting"></span><h4>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h4>
<div class="section" id="s-can-t-find-geos-library">
<span id="can-t-find-geos-library"></span><h5>Can't find GEOS Library<a class="headerlink" href="#can-t-find-geos-library" title="Permalink to this headline">¶</a></h5>
<p>When GeoDjango can't find GEOS, this error is raised:</p>
<div class="highlight-python"><pre>ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.</pre>
</div>
<p>The most common solution is to properly configure your <a class="reference internal" href="#libsettings"><em>Library Environment Settings</em></a> <em>or</em> set
<a class="reference internal" href="#geoslibrarypath"><em>GEOS_LIBRARY_PATH</em></a> in your settings.</p>
<p>If using a binary package of GEOS (e.g., on Ubuntu 8.10), you may need to <a class="reference internal" href="#binutils"><em>Install binutils</em></a>.</p>
</div>
<div class="section" id="s-geos-library-path">
<span id="s-geoslibrarypath"></span><span id="geos-library-path"></span><span id="geoslibrarypath"></span><h5><tt class="docutils literal"><span class="pre">GEOS_LIBRARY_PATH</span></tt><a class="headerlink" href="#geos-library-path" title="Permalink to this headline">¶</a></h5>
<p>If your GEOS library is in a non-standard location, or you don't want to
modify the system's library path then the <a class="reference internal" href="geos.html#std:setting-GEOS_LIBRARY_PATH"><tt class="xref std std-setting docutils literal"><span class="pre">GEOS_LIBRARY_PATH</span></tt></a> setting
may be added to your Django settings file with the full path to the GEOS
C library. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">GEOS_LIBRARY_PATH</span> <span class="o">=</span> <span class="s">'/home/bob/local/lib/libgeos_c.so'</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The setting must be the <em>full</em> path to the <strong>C</strong> shared library; in
other words you want to use <tt class="docutils literal"><span class="pre">libgeos_c.so</span></tt>, not <tt class="docutils literal"><span class="pre">libgeos.so</span></tt>.</p>
</div>
</div>
</div>
</div>
<div class="section" id="s-proj4">
<span id="s-id7"></span><span id="proj4"></span><span id="id7"></span><h3>PROJ.4<a class="headerlink" href="#proj4" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://trac.osgeo.org/proj/">PROJ.4</a> is a library for converting geospatial data to different coordinate
reference systems.</p>
<p>First, download the PROJ.4 source code and datum shifting files <a class="footnote-reference" href="#id56" id="id8">[1]</a>:</p>
<div class="highlight-python"><pre>$ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz
$ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip</pre>
</div>
<p>Next, untar the source code archive, and extract the datum shifting files in the
<tt class="docutils literal"><span class="pre">nad</span></tt> subdirectory. This must be done <em>prior</em> to configuration:</p>
<div class="highlight-python"><pre>$ tar xzf proj-4.7.0.tar.gz
$ cd proj-4.7.0/nad
$ unzip ../../proj-datumgrid-1.5.zip
$ cd ..</pre>
</div>
<p>Finally, configure, make and install PROJ.4:</p>
<div class="highlight-python"><pre>$ ./configure
$ make
$ sudo make install
$ cd ..</pre>
</div>
</div>
<div class="section" id="s-postgis">
<span id="s-id9"></span><span id="postgis"></span><span id="id9"></span><h3>PostGIS<a class="headerlink" href="#postgis" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://postgis.refractions.net/">PostGIS</a> adds geographic object support to PostgreSQL, turning it
into a spatial database. <a class="reference internal" href="#geosbuild"><em>GEOS</em></a> and <a class="reference internal" href="#proj4"><em>PROJ.4</em></a> should be
installed prior to building PostGIS.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference external" href="http://initd.org/projects/psycopg2">psycopg2</a> module is required for use as the database adaptor
when using GeoDjango with PostGIS.</p>
</div>
<p>First download the source archive, and extract:</p>
<div class="highlight-python"><pre>$ wget http://postgis.refractions.net/download/postgis-1.5.1.tar.gz
$ tar xzf postgis-1.5.1.tar.gz
$ cd postgis-1.5.1</pre>
</div>
<p>Next, configure, make and install PostGIS:</p>
<div class="highlight-python"><pre>$ ./configure</pre>
</div>
<p>Finally, make and install:</p>
<div class="highlight-python"><pre>$ make
$ sudo make install
$ cd ..</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">GeoDjango does not automatically create a spatial database. Please
consult the section on <a class="reference internal" href="#spatialdb-template"><em>Creating a Spatial Database Template for PostGIS</em></a> for more information.</p>
</div>
</div>
<div class="section" id="s-gdal">
<span id="s-gdalbuild"></span><span id="gdal"></span><span id="gdalbuild"></span><h3>GDAL<a class="headerlink" href="#gdal" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://trac.osgeo.org/gdal/">GDAL</a> is an excellent open source geospatial library that has support for
reading most vector and raster spatial data formats. Currently, GeoDjango only
supports <a class="reference internal" href="gdal.html#ref-gdal"><em>GDAL's vector data</em></a> capabilities <a class="footnote-reference" href="#id57" id="id11">[2]</a>.
<a class="reference internal" href="#geosbuild"><em>GEOS</em></a> and <a class="reference internal" href="#proj4"><em>PROJ.4</em></a> should be installed prior to building GDAL.</p>
<p>First download the latest GDAL release version and untar the archive:</p>
<div class="highlight-python"><pre>$ wget http://download.osgeo.org/gdal/gdal-1.7.2.tar.gz
$ tar xzf gdal-1.7.2.tar.gz
$ cd gdal-1.7.2</pre>
</div>
<p>Configure, make and install:</p>
<div class="highlight-python"><pre>$ ./configure
$ make # Go get some coffee, this takes a while.
$ sudo make install
$ cd ..</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because GeoDjango has it's own Python interface, the preceding instructions
do not build GDAL's own Python bindings. The bindings may be built by
adding the <tt class="docutils literal"><span class="pre">--with-python</span></tt> flag when running <tt class="docutils literal"><span class="pre">configure</span></tt>. See
<a class="reference external" href="http://trac.osgeo.org/gdal/wiki/GdalOgrInPython">GDAL/OGR In Python</a> for more information on GDAL's bindings.</p>
</div>
<p>If you have any problems, please see the troubleshooting section below for
suggestions and solutions.</p>
<div class="section" id="s-gdaltrouble">
<span id="s-id14"></span><span id="gdaltrouble"></span><span id="id14"></span><h4>Troubleshooting<a class="headerlink" href="#gdaltrouble" title="Permalink to this headline">¶</a></h4>
<div class="section" id="s-can-t-find-gdal-library">
<span id="can-t-find-gdal-library"></span><h5>Can't find GDAL Library<a class="headerlink" href="#can-t-find-gdal-library" title="Permalink to this headline">¶</a></h5>
<p>When GeoDjango can't find the GDAL library, the <tt class="docutils literal"><span class="pre">HAS_GDAL</span></tt> flag
will be false:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.contrib.gis</span> <span class="kn">import</span> <span class="n">gdal</span>
<span class="gp">>>> </span><span class="n">gdal</span><span class="o">.</span><span class="n">HAS_GDAL</span>
<span class="go">False</span>
</pre></div>
</div>
<p>The solution is to properly configure your <a class="reference internal" href="#libsettings"><em>Library Environment Settings</em></a> <em>or</em> set
<a class="reference internal" href="#gdallibrarypath"><em>GDAL_LIBRARY_PATH</em></a> in your settings.</p>
</div>
<div class="section" id="s-gdal-library-path">
<span id="s-gdallibrarypath"></span><span id="gdal-library-path"></span><span id="gdallibrarypath"></span><h5><tt class="docutils literal"><span class="pre">GDAL_LIBRARY_PATH</span></tt><a class="headerlink" href="#gdal-library-path" title="Permalink to this headline">¶</a></h5>
<p>If your GDAL library is in a non-standard location, or you don't want to
modify the system's library path then the <a class="reference internal" href="gdal.html#std:setting-GDAL_LIBRARY_PATH"><tt class="xref std std-setting docutils literal"><span class="pre">GDAL_LIBRARY_PATH</span></tt></a>
setting may be added to your Django settings file with the full path to
the GDAL library. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">GDAL_LIBRARY_PATH</span> <span class="o">=</span> <span class="s">'/home/sue/local/lib/libgdal.so'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-can-t-find-gdal-data-files-gdal-data">
<span id="s-gdaldata"></span><span id="can-t-find-gdal-data-files-gdal-data"></span><span id="gdaldata"></span><h5>Can't find GDAL data files (<tt class="docutils literal"><span class="pre">GDAL_DATA</span></tt>)<a class="headerlink" href="#can-t-find-gdal-data-files-gdal-data" title="Permalink to this headline">¶</a></h5>
<p>When installed from source, GDAL versions 1.5.1 and below have an autoconf bug
that places data in the wrong location. <a class="footnote-reference" href="#id58" id="id15">[3]</a> This can lead to error messages
like this:</p>
<div class="highlight-python"><pre>ERROR 4: Unable to open EPSG support file gcs.csv.
...
OGRException: OGR failure.</pre>
</div>
<p>The solution is to set the <tt class="docutils literal"><span class="pre">GDAL_DATA</span></tt> environment variable to the location of the
GDAL data files before invoking Python (typically <tt class="docutils literal"><span class="pre">/usr/local/share</span></tt>; use
<tt class="docutils literal"><span class="pre">gdal-config</span> <span class="pre">--datadir</span></tt> to find out). For example:</p>
<div class="highlight-python"><pre>$ export GDAL_DATA=`gdal-config --datadir`
$ python manage.py shell</pre>
</div>
<p>If using Apache, you may need to add this environment variable to your configuration
file:</p>
<div class="highlight-python"><pre>SetEnv GDAL_DATA /usr/local/share</pre>
</div>
</div>
</div>
</div>
<div class="section" id="s-spatialite">
<span id="s-id16"></span><span id="spatialite"></span><span id="id16"></span><h3>SpatiaLite<a class="headerlink" href="#spatialite" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.1:</span> <a class="reference internal" href="../../../releases/1.1.html"><em>Please, see the release notes</em></a></div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Mac OS X users should follow the instructions in the <a class="reference internal" href="#kyngchaos"><em>KyngChaos Packages</em></a> section,
as it is much easier than building from source.</p>
</div>
<p><a class="reference external" href="http://www.gaia-gis.it/spatialite/index.html">SpatiaLite</a> adds spatial support to SQLite, turning it into a full-featured
spatial database. Because SpatiaLite has special requirements, it typically
requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from
source. <a class="reference internal" href="#geosbuild"><em>GEOS</em></a> and <a class="reference internal" href="#proj4"><em>PROJ.4</em></a> should be installed prior to building
SpatiaLite.</p>
<p>After installation is complete, don't forget to read the post-installation
docs on <a class="reference internal" href="#create-spatialite-db"><em>Creating a Spatial Database for SpatiaLite</em></a>.</p>
<div class="section" id="s-sqlite">
<span id="s-id18"></span><span id="sqlite"></span><span id="id18"></span><h4>SQLite<a class="headerlink" href="#sqlite" title="Permalink to this headline">¶</a></h4>
<p>Typically, SQLite packages are not compiled to include the <a class="reference external" href="http://www.sqlite.org/rtree.html">R*Tree module</a> --
thus it must be compiled from source. First download the latest amalgamation
source archive from the <a class="reference external" href="http://www.sqlite.org/download.html">SQLite download page</a>, and extract:</p>
<div class="highlight-python"><pre>$ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
$ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
$ cd sqlite-3.6.23.1</pre>
</div>
<p>Next, run the <tt class="docutils literal"><span class="pre">configure</span></tt> script -- however the <tt class="docutils literal"><span class="pre">CFLAGS</span></tt> environment variable
needs to be customized so that SQLite knows to build the R*Tree module:</p>
<div class="highlight-python"><pre>$ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
$ make
$ sudo make install
$ cd ..</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If using Ubuntu, installing a newer SQLite from source can be very difficult
because it links to the existing <tt class="docutils literal"><span class="pre">libsqlite3.so</span></tt> in <tt class="docutils literal"><span class="pre">/usr/lib</span></tt> which
many other packages depend on. Unfortunately, the best solution at this time
is to overwrite the existing library by adding <tt class="docutils literal"><span class="pre">--prefix=/usr</span></tt> to the
<tt class="docutils literal"><span class="pre">configure</span></tt> command.</p>
</div>
</div>
<div class="section" id="s-spatialite-library-libspatialite-and-tools-spatialite">
<span id="s-spatialitebuild"></span><span id="spatialite-library-libspatialite-and-tools-spatialite"></span><span id="spatialitebuild"></span><h4>SpatiaLite Library (<tt class="docutils literal"><span class="pre">libspatialite</span></tt>) and Tools (<tt class="docutils literal"><span class="pre">spatialite</span></tt>)<a class="headerlink" href="#spatialite-library-libspatialite-and-tools-spatialite" title="Permalink to this headline">¶</a></h4>
<p>After SQLite has been built with the R*Tree module enabled, get the latest
SpatiaLite library source and tools bundle from the <a class="reference external" href="http://www.gaia-gis.it/spatialite/sources.html">download page</a>:</p>
<div class="highlight-python"><pre>$ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz
$ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz
$ tar xzf libspatialite-amalgamation-2.3.1.tar.gz
$ tar xzf spatialite-tools-2.3.1.tar.gz</pre>
</div>
<p>Prior to attempting to build, please read the important notes below to see if
customization of the <tt class="docutils literal"><span class="pre">configure</span></tt> command is necessary. If not, then run the
<tt class="docutils literal"><span class="pre">configure</span></tt> script, make, and install for the SpatiaLite library:</p>
<div class="highlight-python"><pre>$ cd libspatialite-amalgamation-2.3.1
$ ./configure # May need to modified, see notes below.
$ make
$ sudo make install
$ cd ..</pre>
</div>
<p>Finally, do the same for the SpatiaLite tools:</p>
<div class="highlight-python"><pre>$ cd spatialite-tools-2.3.1
$ ./configure # May need to modified, see notes below.
$ make
$ sudo make install
$ cd ..</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
their paths when running the <tt class="docutils literal"><span class="pre">configure</span></tt> scripts for <em>both</em> the library and the
tools (the configure scripts look, by default, in <tt class="docutils literal"><span class="pre">/usr/local</span></tt>). For example,
on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be:</p>
<div class="last highlight-python"><pre>$ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib</pre>
</div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>For Mac OS X users building from source, the SpatiaLite library <em>and</em> tools
need to have their <tt class="docutils literal"><span class="pre">target</span></tt> configured:</p>
<div class="last highlight-python"><pre>$ ./configure --target=macosx</pre>
</div>
</div>
</div>
<div class="section" id="s-pysqlite2">
<span id="s-id22"></span><span id="pysqlite2"></span><span id="id22"></span><h4>pysqlite2<a class="headerlink" href="#pysqlite2" title="Permalink to this headline">¶</a></h4>
<p>Because SpatiaLite must be loaded as an external extension, it requires the
<tt class="docutils literal"><span class="pre">enable_load_extension</span></tt> method, which is only available in versions 2.5+.
Thus, download pysqlite2 2.6, and untar:</p>
<div class="highlight-python"><pre>$ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz
$ tar xzf pysqlite-2.6.0.tar.gz
$ cd pysqlite-2.6.0</pre>
</div>
<p>Next, use a text editor (e.g., <tt class="docutils literal"><span class="pre">emacs</span></tt> or <tt class="docutils literal"><span class="pre">vi</span></tt>) to edit the <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file
to look like the following:</p>
<div class="highlight-python"><pre>[build_ext]
#define=
include_dirs=/usr/local/include
library_dirs=/usr/local/lib
libraries=sqlite3
#define=SQLITE_OMIT_LOAD_EXTENSION</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The important thing here is to make sure you comment out the the
<tt class="docutils literal"><span class="pre">define=SQLITE_OMIT_LOAD_EXTENSION</span></tt> flag and that the <tt class="docutils literal"><span class="pre">include_dirs</span></tt>
and <tt class="docutils literal"><span class="pre">library_dirs</span></tt> settings are uncommented and set to the appropriate
path if the SQLite header files and libraries are not in <tt class="docutils literal"><span class="pre">/usr/include</span></tt>
and <tt class="docutils literal"><span class="pre">/usr/lib</span></tt>, respectively.</p>
</div>
<p>After modifying <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> appropriately, then run the <tt class="docutils literal"><span class="pre">setup.py</span></tt> script
to build and install:</p>
<div class="highlight-python"><pre>$ sudo python setup.py install</pre>
</div>
</div>
</div>
</div>
<div class="section" id="s-post-installation">
<span id="post-installation"></span><h2>Post-Installation<a class="headerlink" href="#post-installation" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-creating-a-spatial-database-template-for-postgis">
<span id="s-spatialdb-template"></span><span id="creating-a-spatial-database-template-for-postgis"></span><span id="spatialdb-template"></span><h3>Creating a Spatial Database Template for PostGIS<a class="headerlink" href="#creating-a-spatial-database-template-for-postgis" title="Permalink to this headline">¶</a></h3>
<p>Creating a spatial database with PostGIS is different than normal because
additional SQL must be loaded to enable spatial functionality. Because of
the steps in this process, it's better to create a database template that
can be reused later.</p>
<p>First, you need to be able to execute the commands as a privileged database
user. For example, you can use the following to become the <tt class="docutils literal"><span class="pre">postgres</span></tt> user:</p>
<div class="highlight-python"><pre>$ sudo su - postgres</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The location <em>and</em> name of the PostGIS SQL files (e.g., from
<tt class="docutils literal"><span class="pre">POSTGIS_SQL_PATH</span></tt> below) depends on the version of PostGIS.
PostGIS versions 1.3 and below use <tt class="docutils literal"><span class="pre"><pg_sharedir>/contrib/lwpostgis.sql</span></tt>;
whereas version 1.4 uses <tt class="docutils literal"><span class="pre"><sharedir>/contrib/postgis.sql</span></tt> and
version 1.5 uses <tt class="docutils literal"><span class="pre"><sharedir>/contrib/postgis-1.5/postgis.sql</span></tt>.</p>
<p class="last">The example below assumes PostGIS 1.5, thus you may need to modify
<tt class="docutils literal"><span class="pre">POSTGIS_SQL_PATH</span></tt> and the name of the SQL file for the specific
version of PostGIS you are using.</p>
</div>
<p>Once you're a database super user, then you may execute the following commands
to create a PostGIS spatial database template. If running Ubuntu <a class="reference internal" href="#ibex"><em>8.10</em></a>
or Debian <a class="reference internal" href="#lenny"><em>5.0 (Lenny)</em></a>, please refer to their specific documentation for
modifications to these commands:</p>
<div class="highlight-python"><pre>$ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
# Creating the template spatial database.
$ createdb -E UTF8 template_postgis
$ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
# Allows non-superusers the ability to create from this template
$ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
# Loading the PostGIS SQL routines
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
# Enabling users to alter spatial tables.
$ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
$ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
$ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"</pre>
</div>
<p>These commands may be placed in a shell script for later use; for convenience
the following scripts are available:</p>
<table class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">PostGIS Version</th>
<th class="head">Shell Script</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>1.3</td>
<td><a class="reference external" href="http://geodjango.org/docs/create_template_postgis-1.3.sh">create_template_postgis-1.3.sh</a></td>
</tr>
<tr><td>1.4</td>
<td><a class="reference external" href="http://geodjango.org/docs/create_template_postgis-1.4.sh">create_template_postgis-1.4.sh</a></td>
</tr>
<tr><td>1.5</td>
<td><a class="reference external" href="http://geodjango.org/docs/create_template_postgis-1.5.sh">create_template_postgis-1.5.sh</a></td>
</tr>
</tbody>
</table>
<p>Afterwards, you may create a spatial database by simply specifying
<tt class="docutils literal"><span class="pre">template_postgis</span></tt> as the template to use (via the <tt class="docutils literal"><span class="pre">-T</span></tt> option):</p>
<div class="highlight-python"><pre>$ createdb -T template_postgis <db name></pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>While the <tt class="docutils literal"><span class="pre">createdb</span></tt> command does not require database super-user privileges,
it must be executed by a database user that has permissions to create databases.
You can create such a user with the following command:</p>
<div class="last highlight-python"><pre>$ createuser --createdb <user></pre>
</div>
</div>
</div>
<div class="section" id="s-creating-a-spatial-database-for-spatialite">
<span id="s-create-spatialite-db"></span><span id="creating-a-spatial-database-for-spatialite"></span><span id="create-spatialite-db"></span><h3>Creating a Spatial Database for SpatiaLite<a class="headerlink" href="#creating-a-spatial-database-for-spatialite" title="Permalink to this headline">¶</a></h3>
<p>After the SpatiaLite library and tools have been installed, it is now possible
to create spatial database for use with GeoDjango. In order to do this, download
the spatial database initialization SQL from the <a class="reference external" href="http://www.gaia-gis.it/spatialite/resources.html">SpatiaLite Resources</a> page:</p>
<div class="highlight-python"><pre>$ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.sql.gz
$ gunzip init_spatialite-2.3.sql.gz</pre>
</div>
<p>Now, the <tt class="docutils literal"><span class="pre">spatialite</span></tt> command can be used to initialize a spatial database:</p>
<div class="highlight-python"><pre>$ spatialite geodjango.db < init_spatialite-2.3.sql</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The parameter <tt class="docutils literal"><span class="pre">geodjango.db</span></tt> is the <em>filename</em> of the SQLite database
you want to use. Use the same in the <a class="reference internal" href="../../settings.html#std:setting-DATABASE_NAME"><tt class="xref std std-setting docutils literal"><span class="pre">DATABASE_NAME</span></tt></a>
inside your <tt class="docutils literal"><span class="pre">settings.py</span></tt>.</p>
</div>
</div>
<div class="section" id="s-add-django-contrib-gis-to-installed-apps">
<span id="add-django-contrib-gis-to-installed-apps"></span><h3>Add <tt class="docutils literal"><span class="pre">django.contrib.gis</span></tt> to <tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt><a class="headerlink" href="#add-django-contrib-gis-to-installed-apps" title="Permalink to this headline">¶</a></h3>
<p>Like other Django contrib applications, you will <em>only</em> need to add
<a class="reference internal" href="index.html#module-django.contrib.gis" title="django.contrib.gis: Geographic Information System (GIS) extensions for Django"><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.gis</span></tt></a> to <a class="reference internal" href="../../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> in your settings.
This is the so that <tt class="docutils literal"><span class="pre">gis</span></tt> templates can be located -- if not done, then
features such as the geographic admin or KML sitemaps will not function properly.</p>
</div>
<div class="section" id="s-add-google-projection-to-spatial-ref-sys-table">
<span id="s-addgoogleprojection"></span><span id="add-google-projection-to-spatial-ref-sys-table"></span><span id="addgoogleprojection"></span><h3>Add Google Projection to <tt class="docutils literal"><span class="pre">spatial_ref_sys</span></tt> table<a class="headerlink" href="#add-google-projection-to-spatial-ref-sys-table" title="Permalink to this headline">¶</a></h3>
<div class="versionchanged">
<span class="title">Changed in Django 1.2:</span> <a class="reference internal" href="../../../releases/1.2.html"><em>Please, see the release notes</em></a></div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If running PostGIS 1.4 and above, the entry is already included in the
default <tt class="docutils literal"><span class="pre">spatial_ref_sys</span></tt> table. You can skip this step.</p>
</div>
<p>In order to conduct database transformations to the so-called "Google"
projection (a spherical mercator projection used by Google Maps),
an entry must be added to your spatial database's <tt class="docutils literal"><span class="pre">spatial_ref_sys</span></tt> table.
Invoke the Django shell from your project and execute the
<tt class="docutils literal"><span class="pre">add_srs_entry</span></tt> function:</p>
<div class="highlight-python"><pre>$ python manage shell
>>> from django.contrib.gis.utils import add_srs_entry
>>> add_srs_entry(900913)</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In Django 1.1 the name of this function is <tt class="docutils literal"><span class="pre">add_postgis_srs</span></tt>.</p>
</div>
<p>This adds an entry for the 900913 SRID to the <tt class="docutils literal"><span class="pre">spatial_ref_sys</span></tt> (or equivalent)
table, making it possible for the spatial database to transform coordinates in
this projection. You only need to execute this command <em>once</em> per spatial database.</p>
</div>
</div>
<div class="section" id="s-id24">
<span id="id24"></span><h2>Troubleshooting<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h2>
<p>If you can't find the solution to your problem here then participate in the
community! You can:</p>
<ul class="simple">
<li>Join the <tt class="docutils literal"><span class="pre">#geodjango</span></tt> IRC channel on FreeNode (may be accessed on the
web via <a class="reference external" href="http://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango">Mibbit</a>). Please be patient and polite -- while you may not
get an immediate response, someone will attempt to answer your question
as soon as they see it.</li>
<li>Ask your question on the <a class="reference external" href="http://groups.google.com/group/geodjango">GeoDjango</a> mailing list.</li>
<li>File a ticket on the <a class="reference external" href="http://code.djangoproject.com/simpleticket">Django trac</a> if you think there's a bug. Make
sure to provide a complete description of the problem, versions used,
and specify the component as "GIS".</li>
</ul>
<div class="section" id="s-library-environment-settings">
<span id="s-libsettings"></span><span id="library-environment-settings"></span><span id="libsettings"></span><h3>Library Environment Settings<a class="headerlink" href="#library-environment-settings" title="Permalink to this headline">¶</a></h3>
<p>By far, the most common problem when installing GeoDjango is that the
external shared libraries (e.g., for GEOS and GDAL) cannot be located. <a class="footnote-reference" href="#id59" id="id28">[4]</a>
Typically, the cause of this problem is that the operating system isn't aware
of the directory where the libraries built from source were installed.</p>
<p>In general, the library path may be set on a per-user basis by setting
an environment variable, or by configuring the library path for the entire
system.</p>
<div class="section" id="s-ld-library-path-environment-variable">
<span id="ld-library-path-environment-variable"></span><h4><tt class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></tt> environment variable<a class="headerlink" href="#ld-library-path-environment-variable" title="Permalink to this headline">¶</a></h4>
<p>A user may set this environment variable to customize the library paths
they want to use. The typical library directory for software
built from source is <tt class="docutils literal"><span class="pre">/usr/local/lib</span></tt>. Thus, <tt class="docutils literal"><span class="pre">/usr/local/lib</span></tt> needs
to be included in the <tt class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></tt> variable. For example, the user
could place the following in their bash profile:</p>
<div class="highlight-python"><pre>export LD_LIBRARY_PATH=/usr/local/lib</pre>
</div>
</div>
<div class="section" id="s-setting-system-library-path">
<span id="setting-system-library-path"></span><h4>Setting System Library Path<a class="headerlink" href="#setting-system-library-path" title="Permalink to this headline">¶</a></h4>
<p>On GNU/Linux systems, there is typically a file in <tt class="docutils literal"><span class="pre">/etc/ld.so.conf</span></tt>, which may include
additional paths from files in another directory, such as <tt class="docutils literal"><span class="pre">/etc/ld.so.conf.d</span></tt>.
As the root user, add the custom library path (like <tt class="docutils literal"><span class="pre">/usr/local/lib</span></tt>) on a
new line in <tt class="docutils literal"><span class="pre">ld.so.conf</span></tt>. This is <em>one</em> example of how to do so:</p>
<div class="highlight-python"><pre>$ sudo echo /usr/local/lib >> /etc/ld.so.conf
$ sudo ldconfig</pre>
</div>
<p>For OpenSolaris users, the system library path may be modified using the
<tt class="docutils literal"><span class="pre">crle</span></tt> utility. Run <tt class="docutils literal"><span class="pre">crle</span></tt> with no options to see the current configuration
and use <tt class="docutils literal"><span class="pre">crle</span> <span class="pre">-l</span></tt> to set with the new library path. Be <em>very</em> careful when
modifying the system library path:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># crle -l $OLD_PATH:/usr/local/lib</span>
</pre></div>
</div>
</div>
<div class="section" id="s-install-binutils">
<span id="s-binutils"></span><span id="install-binutils"></span><span id="binutils"></span><h4>Install <tt class="docutils literal"><span class="pre">binutils</span></tt><a class="headerlink" href="#install-binutils" title="Permalink to this headline">¶</a></h4>
<p>GeoDjango uses the <tt class="docutils literal"><span class="pre">find_library</span></tt> function (from the <tt class="docutils literal"><span class="pre">ctypes.util</span></tt> Python
module) to discover libraries. The <tt class="docutils literal"><span class="pre">find_library</span></tt> routine uses a program
called <tt class="docutils literal"><span class="pre">objdump</span></tt> (part of the <tt class="docutils literal"><span class="pre">binutils</span></tt> package) to verify a shared
library on GNU/Linux systems. Thus, if <tt class="docutils literal"><span class="pre">binutils</span></tt> is not installed on your
Linux system then Python's ctypes may not be able to find your library even if
your library path is set correctly and geospatial libraries were built perfectly.</p>
<p>The <tt class="docutils literal"><span class="pre">binutils</span></tt> package may be installed on Debian and Ubuntu systems using the
following command:</p>
<div class="highlight-python"><pre>$ sudo apt-get install binutils</pre>
</div>
<p>Similarly, on Red Hat and CentOS systems:</p>
<div class="highlight-python"><pre>$ sudo yum install binutils</pre>
</div>
</div>
</div>
</div>
<div class="section" id="s-platform-specific-instructions">
<span id="platform-specific-instructions"></span><h2>Platform Specific Instructions<a class="headerlink" href="#platform-specific-instructions" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-mac-os-x">
<span id="s-macosx"></span><span id="mac-os-x"></span><span id="macosx"></span><h3>Mac OS X<a class="headerlink" href="#mac-os-x" title="Permalink to this headline">¶</a></h3>
<p>Because of the variety of packaging systems available for OS X, users have
several different options for installing GeoDjango. These options are:</p>
<ul class="simple">
<li><a class="reference internal" href="#kyngchaos"><em>KyngChaos Packages</em></a></li>
<li><a class="reference internal" href="#fink"><em>Fink</em></a></li>
<li><a class="reference internal" href="#macports"><em>MacPorts</em></a></li>
<li><a class="reference internal" href="#build-from-source"><em>Building from Source</em></a></li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Currently, the easiest and recommended approach for installing GeoDjango
on OS X is to use the KyngChaos packages.</p>
</div>
<p>This section also includes instructions for installing an upgraded version
of <a class="reference internal" href="#macosx-python"><em>Python</em></a> from packages provided by the Python Software
Foundation, however, this is not required.</p>
<div class="section" id="s-python">
<span id="s-macosx-python"></span><span id="python"></span><span id="macosx-python"></span><h4>Python<a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h4>
<p>Although OS X comes with Python installed, users can use framework
installers (<a class="reference external" href="http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg">2.5</a> and <a class="reference external" href="http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg">2.6</a> are available) provided by
the Python Software Foundation. An advantage to using the installer is
that OS X's Python will remain "pristine" for internal operating system
use.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>You will need to modify the <tt class="docutils literal"><span class="pre">PATH</span></tt> environment variable in your
<tt class="docutils literal"><span class="pre">.profile</span></tt> file so that the new version of Python is used when
<tt class="docutils literal"><span class="pre">python</span></tt> is entered at the command-line:</p>
<div class="last highlight-python"><pre>export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH</pre>
</div>
</div>
</div>
<div class="section" id="s-kyngchaos-packages">
<span id="s-kyngchaos"></span><span id="kyngchaos-packages"></span><span id="kyngchaos"></span><h4>KyngChaos Packages<a class="headerlink" href="#kyngchaos-packages" title="Permalink to this headline">¶</a></h4>
<p>William Kyngesburye provides a number of <a class="reference external" href="http://www.kyngchaos.com/software/frameworks">geospatial library binary packages</a>
that make it simple to get GeoDjango installed on OS X without compiling
them from source. However, the <a class="reference external" href="http://developer.apple.com/tools/xcode/">Apple Developer Tools</a> are still necessary
for compiling the Python database adapters <a class="reference internal" href="#psycopg2-kyngchaos"><em>psycopg2</em></a> (for PostGIS)
and <a class="reference internal" href="#pysqlite2-kyngchaos"><em>pysqlite2</em></a> (for SpatiaLite).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">SpatiaLite users should consult the <a class="reference internal" href="#spatialite-kyngchaos"><em>SpatiaLite</em></a> section
after installing the packages for additional instructions.</p>
</div>
<p>Download the framework packages for:</p>
<ul class="simple">
<li>UnixImageIO</li>
<li>PROJ</li>
<li>GEOS</li>
<li>SQLite3 (includes the SpatiaLite library)</li>
<li>GDAL</li>
</ul>
<p>Install the packages in the order they are listed above, as the GDAL and SQLite
packages require the packages listed before them. Afterwards, you can also
install the KyngChaos binary packages for <a class="reference external" href="http://www.kyngchaos.com/software/postgres">PostgreSQL and PostGIS</a>.</p>
<p>After installing the binary packages, you'll want to add the following to
your <tt class="docutils literal"><span class="pre">.profile</span></tt> to be able to run the package programs from the command-line:</p>
<div class="highlight-python"><pre>export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH
export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH
export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH
export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH
export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH
export PATH=/usr/local/pgsql/bin:$PATH</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Use of these binaries requires Django 1.0.3 and above. If you are
using a previous version of Django (like 1.0.2), then you will have
to add the the following in your settings:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">GEOS_LIBRARY_PATH</span><span class="o">=</span><span class="s">'/Library/Frameworks/GEOS.framework/GEOS'</span>
<span class="n">GDAL_LIBRARY_PATH</span><span class="o">=</span><span class="s">'/Library/Frameworks/GDAL.framework/GDAL'</span>
</pre></div>
</div>
</div>
<div class="section" id="s-psycopg2-kyngchaos">
<span id="s-id33"></span><span id="psycopg2-kyngchaos"></span><span id="id33"></span><h5>psycopg2<a class="headerlink" href="#psycopg2-kyngchaos" title="Permalink to this headline">¶</a></h5>
<p>After you've installed the KyngChaos binaries and modified your <tt class="docutils literal"><span class="pre">PATH</span></tt>, as
described above, <tt class="docutils literal"><span class="pre">psycopg2</span></tt> may be installed using the following command:</p>
<div class="highlight-python"><pre>$ sudo python easy_install psycopg2</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To use <tt class="docutils literal"><span class="pre">easy_install</span></tt> you'll need to install Python's <a class="reference external" href="http://pypi.python.org/pypi/setuptools">setuptools</a>.</p>
</div>
</div>
<div class="section" id="s-pysqlite2-kyngchaos">
<span id="s-id34"></span><span id="pysqlite2-kyngchaos"></span><span id="id34"></span><h5>pysqlite2<a class="headerlink" href="#pysqlite2-kyngchaos" title="Permalink to this headline">¶</a></h5>
<p>Follow the <a class="reference internal" href="#pysqlite2"><em>pysqlite2</em></a> source install instructions, however,
when editing the <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> use the following instead:</p>
<div class="highlight-python"><pre>[build_ext]
#define=
include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
libraries=sqlite3
#define=SQLITE_OMIT_LOAD_EXTENSION</pre>
</div>
</div>
<div class="section" id="s-spatialite-kyngchaos">
<span id="s-id35"></span><span id="spatialite-kyngchaos"></span><span id="id35"></span><h5>SpatiaLite<a class="headerlink" href="#spatialite-kyngchaos" title="Permalink to this headline">¶</a></h5>
<p>When <a class="reference internal" href="#create-spatialite-db"><em>Creating a Spatial Database for SpatiaLite</em></a>, the <tt class="docutils literal"><span class="pre">spatialite</span></tt> program is required.
However, instead of attempting to compile the SpatiaLite tools from source,
download the <a class="reference external" href="http://www.gaia-gis.it/spatialite/binaries.html">SpatiaLite Binaries</a> for OS X, and install <tt class="docutils literal"><span class="pre">spatialite</span></tt> in a
location available in your <tt class="docutils literal"><span class="pre">PATH</span></tt>. For example:</p>
<div class="highlight-python"><pre>$ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
$ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
$ cd spatialite-tools-osx-x86-2.3.1/bin
$ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs</pre>
</div>
<p>Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
add the following to your <tt class="docutils literal"><span class="pre">settings.py</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">SPATIALITE_LIBRARY_PATH</span><span class="o">=</span><span class="s">'/Library/Frameworks/SQLite3.framework/SQLite3'</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-fink">
<span id="s-id37"></span><span id="fink"></span><span id="id37"></span><h4>Fink<a class="headerlink" href="#fink" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="http://schwehr.org/blog/">Kurt Schwehr</a> has been gracious enough to create GeoDjango packages for users
of the <a class="reference external" href="http://www.finkproject.org/">Fink</a> package system. The following packages are available, depending
on which version of Python you want to use:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">django-gis-py26</span></tt></li>
<li><tt class="docutils literal"><span class="pre">django-gis-py25</span></tt></li>
<li><tt class="docutils literal"><span class="pre">django-gis-py24</span></tt></li>
</ul>
</div>
<div class="section" id="s-macports">
<span id="s-id40"></span><span id="macports"></span><span id="id40"></span><h4>MacPorts<a class="headerlink" href="#macports" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="http://www.macports.org/">MacPorts</a> may be used to install GeoDjango prerequisites on Macintosh
computers running OS X. Because MacPorts still builds the software from source,
the <a class="reference external" href="http://developer.apple.com/tools/xcode/">Apple Developer Tools</a> are required.</p>
<p>Summary:</p>
<div class="highlight-python"><pre>$ sudo port install postgresql83-server
$ sudo port install geos
$ sudo port install proj
$ sudo port install postgis
$ sudo port install gdal
$ sudo port install libgeoip</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>You will also have to modify the <tt class="docutils literal"><span class="pre">PATH</span></tt> in your <tt class="docutils literal"><span class="pre">.profile</span></tt> so
that the MacPorts programs are accessible from the command-line:</p>
<div class="highlight-python"><pre>export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin</pre>
</div>
<p>In addition, add the <tt class="docutils literal"><span class="pre">FALLBACK_DYLD_LIBRARY_PATH</span></tt> setting so that
the libraries can be found by Python:</p>
<div class="last highlight-python"><pre>export FALLBACK_DYLD_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83</pre>
</div>
</div>
</div>
</div>
<div class="section" id="s-ubuntu-debian-gnu-linux">
<span id="s-ubuntudebian"></span><span id="ubuntu-debian-gnu-linux"></span><span id="ubuntudebian"></span><h3>Ubuntu & Debian GNU/Linux<a class="headerlink" href="#ubuntu-debian-gnu-linux" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-ubuntu">
<span id="s-id42"></span><span id="ubuntu"></span><span id="id42"></span><h4>Ubuntu<a class="headerlink" href="#ubuntu" title="Permalink to this headline">¶</a></h4>
<div class="section" id="s-and-lower">
<span id="s-heron"></span><span id="and-lower"></span><span id="heron"></span><h5>8.04 and lower<a class="headerlink" href="#and-lower" title="Permalink to this headline">¶</a></h5>
<p>The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages,
which is incompatible with GeoDjango. Thus, do <em>not</em> use the binary packages
for GEOS or PostGIS and build some prerequisites from source, per the instructions
in this document; however, it is okay to use the PostgreSQL binary packages.</p>
<p>For more details, please see the Debian instructions for <a class="reference internal" href="#etch"><em>4.0 (Etch)</em></a> below.</p>
</div>
<div class="section" id="s-ibex">
<span id="s-id43"></span><span id="ibex"></span><span id="id43"></span><h5>8.10<a class="headerlink" href="#ibex" title="Permalink to this headline">¶</a></h5>
<p>Use the synaptic package manager to install the following packages:</p>
<div class="highlight-python"><pre>$ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools</pre>
</div>
<p>Afterwards, you may install Django with Python's <tt class="docutils literal"><span class="pre">easy_install</span></tt> script (the
Ubuntu package <tt class="docutils literal"><span class="pre">python-django</span></tt> uses an older version missing several
important bug fixes for GeoDjango):</p>
<div class="highlight-python"><pre>$ sudo easy_install Django</pre>
</div>
<p>That's it! For the curious, the required binary prerequisites packages are:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">binutils</span></tt>: for ctypes to find libraries</li>
<li><tt class="docutils literal"><span class="pre">postgresql-8.3</span></tt></li>
<li><tt class="docutils literal"><span class="pre">postgresql-server-dev-8.3</span></tt>: for <tt class="docutils literal"><span class="pre">pg_config</span></tt></li>
<li><tt class="docutils literal"><span class="pre">postgresql-8.3-postgis</span></tt>: for PostGIS 1.3.3</li>
<li><tt class="docutils literal"><span class="pre">libgeos-3.0.0</span></tt>, and <tt class="docutils literal"><span class="pre">libgeos-c1</span></tt>: for GEOS 3.0.0</li>
<li><tt class="docutils literal"><span class="pre">libgdal1-1.5.0</span></tt>: for GDAL 1.5.0 library</li>
<li><tt class="docutils literal"><span class="pre">proj</span></tt>: for PROJ 4.6.0 -- but no datum shifting files, see note below</li>
<li><tt class="docutils literal"><span class="pre">python-psycopg2</span></tt></li>
<li><tt class="docutils literal"><span class="pre">python-setuptools</span></tt>: for <tt class="docutils literal"><span class="pre">easy_install</span></tt></li>
</ul>
<p>Optional packages to consider:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">libgeoip1</span></tt>: for <a class="reference internal" href="geoip.html#ref-geoip"><em>GeoIP</em></a> support</li>
<li><tt class="docutils literal"><span class="pre">gdal-bin</span></tt>: for GDAL command line programs like <tt class="docutils literal"><span class="pre">ogr2ogr</span></tt></li>
<li><tt class="docutils literal"><span class="pre">python-gdal</span></tt> for GDAL's own Python bindings -- includes interfaces for raster manipulation</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The Ubuntu <tt class="docutils literal"><span class="pre">proj</span></tt> package does not come with the datum shifting files
installed, which will cause problems with the geographic admin because
the <tt class="docutils literal"><span class="pre">null</span></tt> datum grid is not available for transforming geometries to the
spherical mercator projection. A solution is to download the
datum-shifting files, create the grid file, and install it yourself:</p>
<div class="highlight-python"><pre>$ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz
$ mkdir nad
$ cd nad
$ tar xzf ../proj-datumgrid-1.4.tar.gz
$ nad2bin null < null.lla
$ sudo cp null /usr/share/proj</pre>
</div>
<p class="last">Otherwise, the Ubuntu <tt class="docutils literal"><span class="pre">proj</span></tt> package is fine for general use as long as you
do not plan on doing any database transformation of geometries to the
Google projection (900913).</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The PostGIS SQL files are not placed the PostgreSQL share directory in the
Ubuntu packages. Use the <a class="reference external" href="http://geodjango.org/docs/create_template_postgis-debian.sh">create_template_postgis-debian.sh</a> script
instead when <a class="reference internal" href="#spatialdb-template"><em>Creating a Spatial Database Template for PostGIS</em></a>.</p>
</div>
</div>
</div>
</div>
<div class="section" id="s-debian">
<span id="s-id44"></span><span id="debian"></span><span id="id44"></span><h3>Debian<a class="headerlink" href="#debian" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-etch">
<span id="s-id45"></span><span id="etch"></span><span id="id45"></span><h4>4.0 (Etch)<a class="headerlink" href="#etch" title="Permalink to this headline">¶</a></h4>
<p>The situation here is the same as that of Ubuntu <a class="reference internal" href="#heron"><em>8.04 and lower</em></a> -- in other words,
some packages must be built from source to work properly with GeoDjango.</p>
<div class="section" id="s-binary-packages">
<span id="binary-packages"></span><h5>Binary Packages<a class="headerlink" href="#binary-packages" title="Permalink to this headline">¶</a></h5>
<p>The following command will install acceptable binary packages, as well as
the development tools necessary to build the rest of the requirements:</p>
<div class="highlight-python"><pre>$ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools</pre>
</div>
<p>Required package information:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">binutils</span></tt>: for ctypes to find libraries</li>
<li><tt class="docutils literal"><span class="pre">bzip2</span></tt>: for decompressing the source packages</li>
<li><tt class="docutils literal"><span class="pre">gcc</span></tt>, <tt class="docutils literal"><span class="pre">g++</span></tt>, <tt class="docutils literal"><span class="pre">make</span></tt>: GNU developer tools used to compile the libraries</li>
<li><tt class="docutils literal"><span class="pre">flex</span></tt>: required to build PostGIS</li>
<li><tt class="docutils literal"><span class="pre">postgresql-8.1</span></tt></li>
<li><tt class="docutils literal"><span class="pre">postgresql-server-dev-8.1</span></tt>: for <tt class="docutils literal"><span class="pre">pg_config</span></tt></li>
<li><tt class="docutils literal"><span class="pre">python-ctypes</span></tt>: Python 2.4 needs to have ctypes installed separately</li>
<li><tt class="docutils literal"><span class="pre">python-psycopg2</span></tt></li>
<li><tt class="docutils literal"><span class="pre">python-setuptools</span></tt>: for <tt class="docutils literal"><span class="pre">easy_install</span></tt></li>
</ul>
<p>Optional packages:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">libgeoip</span></tt>: for <a class="reference internal" href="geoip.html#ref-geoip"><em>GeoIP</em></a> support</li>
</ul>
</div>
<div class="section" id="s-source-packages">
<span id="source-packages"></span><h5>Source Packages<a class="headerlink" href="#source-packages" title="Permalink to this headline">¶</a></h5>
<p>You will still have to install <a class="reference internal" href="#geosbuild"><em>GEOS</em></a>, <a class="reference internal" href="#proj4"><em>PROJ.4</em></a>,
<a class="reference internal" href="#postgis"><em>PostGIS</em></a>, and <a class="reference internal" href="#gdalbuild"><em>GDAL</em></a> from source. Please follow the
directions carefully.</p>
</div>
</div>
<div class="section" id="s-lenny">
<span id="s-id46"></span><span id="lenny"></span><span id="id46"></span><h4>5.0 (Lenny)<a class="headerlink" href="#lenny" title="Permalink to this headline">¶</a></h4>
<p>This version is comparable to Ubuntu <a class="reference internal" href="#ibex"><em>8.10</em></a>, so the command
is very similar:</p>
<div class="highlight-python"><pre>$ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools</pre>
</div>
<p>This assumes that you are using PostgreSQL version 8.3. Else, replace <tt class="docutils literal"><span class="pre">8.3</span></tt>
in the above command with the appropriate PostgreSQL version.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Please read the note in the Ubuntu <a class="reference internal" href="#ibex"><em>8.10</em></a> install documentation
about the <tt class="docutils literal"><span class="pre">proj</span></tt> package -- it also applies here because the package does
not include the datum shifting files.</p>
</div>
<div class="section" id="s-post-installation-notes">
<span id="s-post-install"></span><span id="post-installation-notes"></span><span id="post-install"></span><h5>Post-installation Notes<a class="headerlink" href="#post-installation-notes" title="Permalink to this headline">¶</a></h5>
<p>If the PostgreSQL database cluster was not initiated after installing, then it
can be created (and started) with the following command:</p>
<div class="highlight-python"><pre>$ sudo pg_createcluster --start 8.3 main</pre>
</div>
<p>Afterwards, the <tt class="docutils literal"><span class="pre">/etc/init.d/postgresql-8.3</span></tt> script should be used to manage
the starting and stopping of PostgreSQL.</p>
<p>In addition, the SQL files for PostGIS are placed in a different location on
Debian 5.0 . Thus when <a class="reference internal" href="#spatialdb-template"><em>Creating a Spatial Database Template for PostGIS</em></a> either:</p>
<ul>
<li><p class="first">Create a symbolic link to these files:</p>
<div class="highlight-python"><pre>$ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql /usr/share/postgresql/8.3</pre>
</div>
<p>If not running PostgreSQL 8.3, then replace <tt class="docutils literal"><span class="pre">8.3</span></tt> in the command above with the correct version.</p>
</li>
<li><p class="first">Or use the <a class="reference external" href="http://geodjango.org/docs/create_template_postgis-debian.sh">create_template_postgis-debian.sh</a> to create the spatial database.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="s-windows-xp">
<span id="s-windows"></span><span id="windows-xp"></span><span id="windows"></span><h3>Windows XP<a class="headerlink" href="#windows-xp" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-id47">
<span id="id47"></span><h4>Python<a class="headerlink" href="#id47" title="Permalink to this headline">¶</a></h4>
<p>First, download the <a class="reference external" href="http://python.org/ftp/python/2.6.2/python-2.6.2.msi">Python 2.6 installer</a> from the Python website. Next,
execute the installer and use defaults, e.g., keep 'Install for all users'
checked and the installation path set as <tt class="docutils literal"><span class="pre">C:\Python26</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You may already have a version of Python installed in <tt class="docutils literal"><span class="pre">C:\python</span></tt> as ESRI
products sometimes install a copy there. <em>You should still install a
fresh version of Python 2.6.</em></p>
</div>
</div>
<div class="section" id="s-postgresql">
<span id="postgresql"></span><h4>PostgreSQL<a class="headerlink" href="#postgresql" title="Permalink to this headline">¶</a></h4>
<p>First, select a mirror and download the latest <a class="reference external" href="http://www.enterprisedb.com/products/pgdownload.do#windows">PostgreSQL 8.3 installer</a> from
the EnterpriseDB website.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">PostgreSQL 8.3 is required because PostGIS is not available yet for 8.4.</p>
</div>
<p>After downloading, simply click on the installer, follow the
on-screen directions, and keep the default options (e.g., keep the installation
path as <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\PostgreSQL\8.3</span></tt>).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This PostgreSQL installation process will create both a new windows user to be the
'postgres service account' and a special 'postgres superuser' to own the database
cluster. You will be prompted to set a password for both users (make sure to write
them down!). To see basic details on the 'service user' account right click on
'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools ->
Computer Management -> System Tools -> Local Users and Groups.</p>
</div>
<p>If installed successfully, the PostgreSQL server will run in the background each time
the system as started as a Windows service. When finished, the installer should launch
the Application Stack Builder (ASB) -- use this to install PostGIS, see instructions
below for more details. A 'PostgreSQL 8.3' start menu group should be created that
contains shortcuts for the ASB and 'Command Prompt', which launches a terminal window
in the PostgreSQL directory.</p>
</div>
<div class="section" id="s-id50">
<span id="id50"></span><h4>PostGIS<a class="headerlink" href="#id50" title="Permalink to this headline">¶</a></h4>
<p>From the Application Stack Builder (Programs -> PostgreSQL 8.3), select
'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next,
select 'PostGIS 1.3.6 for PostgreSQL 8.3' from the 'Spatial Extensions' tree
in the list. Select only the default options during install (do not uncheck
the option to create a default PostGIS database).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You will be prompted to enter your 'postgres superuser' password in the
'Database Connection Information' dialog.</p>
</div>
</div>
<div class="section" id="s-id51">
<span id="id51"></span><h4>psycopg2<a class="headerlink" href="#id51" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">psycopg2</span></tt> Python module provides the interface between Python and the
PostgreSQL database. Download the <a class="reference external" href="http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.10.win32-py2.6-pg8.3.7-release.exe">Windows installer</a> (v2.0.10) and run
using the default settings. <a class="footnote-reference" href="#id60" id="id52">[5]</a></p>
</div>
<div class="section" id="s-geodjango-installer">
<span id="geodjango-installer"></span><h4>GeoDjango Installer<a class="headerlink" href="#geodjango-installer" title="Permalink to this headline">¶</a></h4>
<p>Download the <a class="reference external" href="http://geodjango.org/windows/GeoDjango_Installer.exe">GeoDjango Installer</a>; this was created <a class="footnote-reference" href="#id61" id="id54">[6]</a> to simplify the rest
of the process for installing GeoDjango on Windows platforms. The installer
automatically installs Django 1.1, GDAL 1.6.0, PROJ 4.6.1 (including datum grid
files), and configures the necessary environment variables.</p>
<p>Once the installer has completed, log out and log back in so that the
modifications to the system environment variables take effect, and you
should be good to go.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The installer modifies the system <tt class="docutils literal"><span class="pre">Path</span></tt> environment variable to
include <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\PostgreSQL\8.3\bin</span></tt> and
<tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\GeoDjango\bin</span></tt>. This is required so that Python
may find the GEOS DLL provided by PostGIS and the GDAL DLL provided
by the installer. The installer also sets the <tt class="docutils literal"><span class="pre">GDAL_DATA</span></tt> and
<tt class="docutils literal"><span class="pre">PROJ_LIB</span></tt> environment variables.</p>
</div>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id56" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id8">[1]</a></td><td>The datum shifting files are needed for converting data to and from certain projections.
For example, the PROJ.4 string for the <a class="reference external" href="http://spatialreference.org/ref/epsg/900913/proj4">Google projection (900913)</a>
requires the <tt class="docutils literal"><span class="pre">null</span></tt> grid file only included in the extra datum shifting files.
It is easier to install the shifting files now, then to have debug a problem caused by their absence later.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id57" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id11">[2]</a></td><td>Specifically, GeoDjango provides support for the <a class="reference external" href="http://gdal.org/ogr">OGR</a> library, a component of GDAL.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id58" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id15">[3]</a></td><td>See <a class="reference external" href="http://trac.osgeo.org/gdal/ticket/2382">GDAL ticket #2382</a>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id59" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id28">[4]</a></td><td>GeoDjango uses the <a class="reference external" href="http://docs.python.org/library/ctypes.html#finding-shared-libraries">find_library</a>
routine from <tt class="docutils literal"><span class="pre">ctypes.util</span></tt> to locate shared libraries.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id60" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id52">[5]</a></td><td>The <tt class="docutils literal"><span class="pre">psycopg2</span></tt> Windows installers are packaged and maintained by
<a class="reference external" href="http://www.stickpeople.com/projects/python/win-psycopg/">Jason Erickson</a>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id61" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id54">[6]</a></td><td>The source code for the installer is available in the <a class="reference external" href="http://geodjango.org/hg/nsis_installer/">nsis_installer</a>
GeoDjango mercurial repository.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">GeoDjango Installation</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#requirements">Requirements</a><ul>
<li><a class="reference internal" href="#python-2-4">Python 2.4+</a></li>
<li><a class="reference internal" href="#django">Django</a></li>
<li><a class="reference internal" href="#spatial-database">Spatial Database</a></li>
<li><a class="reference internal" href="#geospatial-libraries">Geospatial Libraries</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-from-source">Building from Source</a><ul>
<li><a class="reference internal" href="#geos">GEOS</a><ul>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li><a class="reference internal" href="#can-t-find-geos-library">Can’t find GEOS Library</a></li>
<li><a class="reference internal" href="#geos-library-path"><tt class="docutils literal"><span class="pre">GEOS_LIBRARY_PATH</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#proj4">PROJ.4</a></li>
<li><a class="reference internal" href="#postgis">PostGIS</a></li>
<li><a class="reference internal" href="#gdal">GDAL</a><ul>
<li><a class="reference internal" href="#gdaltrouble">Troubleshooting</a><ul>
<li><a class="reference internal" href="#can-t-find-gdal-library">Can’t find GDAL Library</a></li>
<li><a class="reference internal" href="#gdal-library-path"><tt class="docutils literal"><span class="pre">GDAL_LIBRARY_PATH</span></tt></a></li>
<li><a class="reference internal" href="#can-t-find-gdal-data-files-gdal-data">Can’t find GDAL data files (<tt class="docutils literal"><span class="pre">GDAL_DATA</span></tt>)</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#spatialite">SpatiaLite</a><ul>
<li><a class="reference internal" href="#sqlite">SQLite</a></li>
<li><a class="reference internal" href="#spatialite-library-libspatialite-and-tools-spatialite">SpatiaLite Library (<tt class="docutils literal"><span class="pre">libspatialite</span></tt>) and Tools (<tt class="docutils literal"><span class="pre">spatialite</span></tt>)</a></li>
<li><a class="reference internal" href="#pysqlite2">pysqlite2</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#post-installation">Post-Installation</a><ul>
<li><a class="reference internal" href="#creating-a-spatial-database-template-for-postgis">Creating a Spatial Database Template for PostGIS</a></li>
<li><a class="reference internal" href="#creating-a-spatial-database-for-spatialite">Creating a Spatial Database for SpatiaLite</a></li>
<li><a class="reference internal" href="#add-django-contrib-gis-to-installed-apps">Add <tt class="docutils literal"><span class="pre">django.contrib.gis</span></tt> to <tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a></li>
<li><a class="reference internal" href="#add-google-projection-to-spatial-ref-sys-table">Add Google Projection to <tt class="docutils literal"><span class="pre">spatial_ref_sys</span></tt> table</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id24">Troubleshooting</a><ul>
<li><a class="reference internal" href="#library-environment-settings">Library Environment Settings</a><ul>
<li><a class="reference internal" href="#ld-library-path-environment-variable"><tt class="docutils literal"><span class="pre">LD_LIBRARY_PATH</span></tt> environment variable</a></li>
<li><a class="reference internal" href="#setting-system-library-path">Setting System Library Path</a></li>
<li><a class="reference internal" href="#install-binutils">Install <tt class="docutils literal"><span class="pre">binutils</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#platform-specific-instructions">Platform Specific Instructions</a><ul>
<li><a class="reference internal" href="#mac-os-x">Mac OS X</a><ul>
<li><a class="reference internal" href="#python">Python</a></li>
<li><a class="reference internal" href="#kyngchaos-packages">KyngChaos Packages</a><ul>
<li><a class="reference internal" href="#psycopg2-kyngchaos">psycopg2</a></li>
<li><a class="reference internal" href="#pysqlite2-kyngchaos">pysqlite2</a></li>
<li><a class="reference internal" href="#spatialite-kyngchaos">SpatiaLite</a></li>
</ul>
</li>
<li><a class="reference internal" href="#fink">Fink</a></li>
<li><a class="reference internal" href="#macports">MacPorts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ubuntu-debian-gnu-linux">Ubuntu & Debian GNU/Linux</a><ul>
<li><a class="reference internal" href="#ubuntu">Ubuntu</a><ul>
<li><a class="reference internal" href="#and-lower">8.04 and lower</a></li>
<li><a class="reference internal" href="#ibex">8.10</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#debian">Debian</a><ul>
<li><a class="reference internal" href="#etch">4.0 (Etch)</a><ul>
<li><a class="reference internal" href="#binary-packages">Binary Packages</a></li>
<li><a class="reference internal" href="#source-packages">Source Packages</a></li>
</ul>
</li>
<li><a class="reference internal" href="#lenny">5.0 (Lenny)</a><ul>
<li><a class="reference internal" href="#post-installation-notes">Post-installation Notes</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#windows-xp">Windows XP</a><ul>
<li><a class="reference internal" href="#id47">Python</a></li>
<li><a class="reference internal" href="#postgresql">PostgreSQL</a></li>
<li><a class="reference internal" href="#id50">PostGIS</a></li>
<li><a class="reference internal" href="#id51">psycopg2</a></li>
<li><a class="reference internal" href="#geodjango-installer">GeoDjango Installer</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="tutorial.html">GeoDjango Tutorial</a></li>
<li>Next: <a href="model-api.html">GeoDjango Model API</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../../index.html">Django v1.2 documentation</a>
<ul><li><a href="../../index.html">API Reference</a>
<ul><li><a href="../index.html"><tt class="docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal docutils literal"><span class="pre">contrib</span></tt> packages</a>
<ul><li><a href="index.html">GeoDjango</a>
<ul><li>GeoDjango Installation</li></ul>
</li></ul></li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/ref/contrib/gis/install.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Oct 20, 2010</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="tutorial.html" title="GeoDjango Tutorial">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="model-api.html" title="GeoDjango Model API">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
i586
>
media
>
main
>
by-pkgid
>
5fcb1fedf34660bc240dc59b7bfcebc4
>
files
>
354
