mirror of https://github.com/django/django.git
244 lines
7.9 KiB
Plaintext
244 lines
7.9 KiB
Plaintext
===============================
|
|
Installing Geospatial libraries
|
|
===============================
|
|
|
|
GeoDjango uses and/or provides interfaces for the following open source
|
|
geospatial libraries:
|
|
|
|
======================== ==================================== ================================ ===================================
|
|
Program Description Required Supported Versions
|
|
======================== ==================================== ================================ ===================================
|
|
:doc:`GEOS <../geos>` Geometry Engine Open Source Yes 3.8, 3.7, 3.6, 3.5
|
|
`PROJ`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 6.x, 5.x, 4.x
|
|
:doc:`GDAL <../gdal>` Geospatial Data Abstraction Library Yes 3.1, 3.0, 2.4, 2.3, 2.2, 2.1, 2.0
|
|
:doc:`GeoIP <../geoip2>` IP-based geolocation library No 2
|
|
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 3.0, 2.5, 2.4, 2.3
|
|
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 4.3
|
|
======================== ==================================== ================================ ===================================
|
|
|
|
Note that older or more recent versions of these libraries *may* also work
|
|
totally fine with GeoDjango. Your mileage may vary.
|
|
|
|
..
|
|
Libs release dates:
|
|
GEOS 3.5.0 2015-08-15
|
|
GEOS 3.6.0 2016-10-25
|
|
GEOS 3.7.0 2018-09-10
|
|
GEOS 3.8.0 2019-10-10
|
|
GDAL 2.0.0 2015-06
|
|
GDAL 2.1.0 2016-04
|
|
GDAL 2.2.0 2017-05
|
|
GDAL 2.3.0 2018-05
|
|
GDAL 2.4.0 2018-12
|
|
GDAL 3.0.0 2019-05
|
|
GDAL 3.1.0 2020-05-07
|
|
PostGIS 2.3.0 2016-09-26
|
|
PostGIS 2.4.0 2017-09-30
|
|
PostGIS 2.5.0 2018-09-23
|
|
PostGIS 3.0.0 2019-10-20
|
|
SpatiaLite 4.3.0 2015-09-07
|
|
|
|
.. note::
|
|
|
|
The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
|
|
independently of Django. In other words, no database or settings file
|
|
required -- import them as normal from :mod:`django.contrib.gis`.
|
|
|
|
.. _PROJ: https://proj.org/
|
|
__ https://postgis.net/
|
|
__ https://www.gaia-gis.it/gaia-sins/
|
|
|
|
|
|
On Debian/Ubuntu, you are advised to install the following packages which will
|
|
install, directly or by dependency, the required geospatial libraries:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo apt-get install binutils libproj-dev gdal-bin
|
|
|
|
Please also consult platform-specific instructions if you are on :ref:`macos`
|
|
or :ref:`windows`.
|
|
|
|
.. _build_from_source:
|
|
|
|
Building from source
|
|
====================
|
|
|
|
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.
|
|
|
|
.. note::
|
|
|
|
On Linux platforms, it may be necessary to run the ``ldconfig`` command
|
|
after installing each library. For example::
|
|
|
|
$ sudo make install
|
|
$ sudo ldconfig
|
|
|
|
.. note::
|
|
|
|
macOS users must install `Xcode`_ in order to compile software from source.
|
|
|
|
.. _Xcode: https://developer.apple.com/xcode/
|
|
|
|
.. _geosbuild:
|
|
|
|
GEOS
|
|
----
|
|
|
|
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., ``libgeos_c.so``)
|
|
directly from Python using ctypes.
|
|
|
|
First, download GEOS from the GEOS website and untar the source archive::
|
|
|
|
$ wget https://download.osgeo.org/geos/geos-X.Y.Z.tar.bz2
|
|
$ tar xjf geos-X.Y.Z.tar.bz2
|
|
|
|
Next, change into the directory where GEOS was unpacked, run the configure
|
|
script, compile, and install::
|
|
|
|
$ cd geos-X.Y.Z
|
|
$ ./configure
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
Troubleshooting
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Can't find GEOS library
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When GeoDjango can't find GEOS, this error is raised:
|
|
|
|
.. code-block:: text
|
|
|
|
ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
|
|
|
|
The most common solution is to properly configure your :ref:`libsettings` *or* set
|
|
:ref:`geoslibrarypath` in your settings.
|
|
|
|
If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`.
|
|
|
|
.. _geoslibrarypath:
|
|
|
|
``GEOS_LIBRARY_PATH``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If your GEOS library is in a non-standard location, or you don't want to
|
|
modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
|
|
setting may be added to your Django settings file with the full path to the
|
|
GEOS C library. For example::
|
|
|
|
GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
|
|
|
|
.. note::
|
|
|
|
The setting must be the *full* path to the **C** shared library; in
|
|
other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
|
|
|
|
See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
|
|
|
|
.. _proj4:
|
|
|
|
PROJ
|
|
----
|
|
|
|
`PROJ`_ is a library for converting geospatial data to different coordinate
|
|
reference systems.
|
|
|
|
First, download the PROJ source code and datum shifting files [#]_::
|
|
|
|
$ wget https://download.osgeo.org/proj/proj-X.Y.Z.tar.gz
|
|
$ wget https://download.osgeo.org/proj/proj-datumgrid-X.Y.tar.gz
|
|
|
|
Next, untar the source code archive, and extract the datum shifting files in the
|
|
``nad`` subdirectory. This must be done *prior* to configuration::
|
|
|
|
$ tar xzf proj-X.Y.Z.tar.gz
|
|
$ cd proj-X.Y.Z/nad
|
|
$ tar xzf ../../proj-datumgrid-X.Y.tar.gz
|
|
$ cd ..
|
|
|
|
Finally, configure, make and install PROJ::
|
|
|
|
$ ./configure
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. _gdalbuild:
|
|
|
|
GDAL
|
|
----
|
|
|
|
`GDAL`__ is an excellent open source geospatial library that has support for
|
|
reading most vector and raster spatial data formats. Currently, GeoDjango only
|
|
supports :doc:`GDAL's vector data <../gdal>` capabilities [#]_.
|
|
:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
|
|
|
|
First download the latest GDAL release version and untar the archive::
|
|
|
|
$ wget https://download.osgeo.org/gdal/X.Y.Z/gdal-X.Y.Z.tar.gz
|
|
$ tar xzf gdal-X.Y.Z.tar.gz
|
|
$ cd gdal-X.Y.Z
|
|
|
|
Configure, make and install::
|
|
|
|
$ ./configure
|
|
$ make # Go get some coffee, this takes a while.
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. note::
|
|
|
|
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 ``--with-python`` flag when running ``configure``. See
|
|
`GDAL/OGR In Python`__ for more information on GDAL's bindings.
|
|
|
|
If you have any problems, please see the troubleshooting section below for
|
|
suggestions and solutions.
|
|
|
|
__ https://trac.osgeo.org/gdal/
|
|
__ https://trac.osgeo.org/gdal/wiki/GdalOgrInPython
|
|
|
|
.. _gdaltrouble:
|
|
|
|
Troubleshooting
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Can't find GDAL library
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When GeoDjango can't find the GDAL library, configure your :ref:`libsettings`
|
|
*or* set :ref:`gdallibrarypath` in your settings.
|
|
|
|
.. _gdallibrarypath:
|
|
|
|
``GDAL_LIBRARY_PATH``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If your GDAL library is in a non-standard location, or you don't want to
|
|
modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
|
|
setting may be added to your Django settings file with the full path to
|
|
the GDAL library. For example::
|
|
|
|
GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
|
|
|
|
.. rubric:: Footnotes
|
|
.. [#] The datum shifting files are needed for converting data to and from
|
|
certain projections.
|
|
For example, the PROJ string for the `Google projection (900913 or 3857)
|
|
<https://spatialreference.org/ref/sr-org/6864/prj/>`_ requires the
|
|
``null`` 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.
|
|
.. [#] Specifically, GeoDjango provides support for the `OGR
|
|
<https://gdal.org/user/vector_data_model.html>`_ library, a component of
|
|
GDAL.
|