<!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>Installing Geospatial libraries — Django 1.6.7 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.6.7',
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 1.6.7 documentation" href="../../../../index.html" />
<link rel="up" title="GeoDjango Installation" href="index.html" />
<link rel="next" title="Installing PostGIS" href="postgis.html" />
<link rel="prev" title="GeoDjango Installation" href="index.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 1.6.7 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="index.html" title="GeoDjango Installation">previous</a>
|
<a href="../../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="postgis.html" title="Installing PostGIS">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-gis-install-geolibs">
<div class="section" id="s-installing-geospatial-libraries">
<span id="s-geospatial-libs"></span><span id="installing-geospatial-libraries"></span><span id="geospatial-libs"></span><h1>Installing Geospatial libraries<a class="headerlink" href="#installing-geospatial-libraries" title="Permalink to this headline">¶</a></h1>
<p>GeoDjango uses and/or provides interfaces for 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 class="row-odd"><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 class="row-even"><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.3, 3.2, 3.1, 3.0</td>
</tr>
<tr class="row-odd"><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.8, 4.7, 4.6, 4.5, 4.4</td>
</tr>
<tr class="row-even"><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.9, 1.8, 1.7, 1.6, 1.5</td>
</tr>
<tr class="row-odd"><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 class="row-even"><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>2.0, 1.5, 1.4, 1.3</td>
</tr>
<tr class="row-odd"><td><a class="reference external" href="http://www.gaia-gis.it/gaia-sins/">SpatiaLite</a></td>
<td>Spatial extensions for SQLite</td>
<td>Yes (SQLite only)</td>
<td>3.0, 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>.
Important features of GeoDjango (including the <a class="reference internal" href="../layermapping.html#ref-layermapping"><em>LayerMapping data import utility</em></a>,
geometry reprojection, 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>
<p>On Debian/Ubuntu, you are advised to install the following packages which will
install, directly or by dependency, the required geospatial libraries:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>sudo apt-get install binutils libproj-dev gdal-bin
</pre></div>
</div>
<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>
<p>Please also consult platform-specific instructions if you are on <a class="reference internal" href="index.html#macosx"><em>Mac OS X</em></a>
or <a class="reference internal" href="index.html#windows"><em>Windows</em></a>.</p>
<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 necessary 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="https://developer.apple.com/technologies/tools/">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.3.8 from the refractions Web site and untar the source
archive:</p>
<div class="highlight-python"><pre>$ wget http://download.osgeo.org/geos/geos-3.3.8.tar.bz2
$ tar xjf geos-3.3.8.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.3.8
$ ./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-text"><div class="highlight"><pre>ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
</pre></div>
</div>
<p>The most common solution is to properly configure your <a class="reference internal" href="index.html#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), you may need to <a class="reference internal" href="index.html#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>
<p>See also <a class="reference internal" href="../geos.html#geos-exceptions-in-logfile"><em>My logs are filled with GEOS-related errors</em></a>.</p>
</div>
</div>
</div>
<div class="section" id="s-proj4">
<span id="s-id3"></span><span id="proj4"></span><span id="id3"></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="#id10" id="id4">[1]</a>:</p>
<div class="highlight-python"><pre>$ wget http://download.osgeo.org/proj/proj-4.8.0.tar.gz
$ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.tar.gz</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.8.0.tar.gz
$ cd proj-4.8.0/nad
$ tar xzf ../../proj-datumgrid-1.5.tar.gz
$ 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-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="#id11" id="id5">[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.9.2.tar.gz
$ tar xzf gdal-1.9.2.tar.gz
$ cd gdal-1.9.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 its 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-id8"></span><span id="gdaltrouble"></span><span id="id8"></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="index.html#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="#id12" id="id9">[3]</a> This can lead to error messages
like this:</p>
<div class="highlight-text"><div class="highlight"><pre>ERROR 4: Unable to open EPSG support file gcs.csv.
...
OGRException: OGR failure.
</pre></div>
</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-apache"><div class="highlight"><pre><span class="nb">SetEnv</span> GDAL_DATA <span class="sx">/usr/local/share</span>
</pre></div>
</div>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[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/sr-org/6864/prj/">Google projection (900913 or 3857)</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="id11" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[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="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9">[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>
</div>
</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="#">Installing Geospatial libraries</a><ul>
<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="#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>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="index.html">GeoDjango Installation</a></li>
<li>Next: <a href="postgis.html">Installing PostGIS</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../../../index.html">Django 1.6.7 documentation</a>
<ul><li><a href="../../../index.html">API Reference</a>
<ul><li><a href="../../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a>
<ul><li><a href="../index.html">GeoDjango</a>
<ul><li><a href="index.html">GeoDjango Installation</a>
<ul><li>Installing Geospatial libraries</li></ul>
</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/geolibs.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" />
<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">Sep 26, 2014</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="index.html" title="GeoDjango Installation">previous</a>
|
<a href="../../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="postgis.html" title="Installing PostGIS">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
