<!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.5.9 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.5.9', 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.5.9 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.5.9 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.5 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.5.tar.bz2 $ tar xjf geos-3.3.5.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.5 $ ./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.1.tar.gz $ tar xzf gdal-1.9.1.tar.gz $ cd gdal-1.9.1</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-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-pycon"><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.5.9 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">Mar 19, 2015</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>