mirror of
https://github.com/django/django.git
synced 2024-12-30 13:05:45 +00:00
b784768eef
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for
reviews.
Backport of 534ac48297 from main.
304 lines
9.1 KiB
Plaintext
304 lines
9.1 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.11, 3.10, 3.9, 3.8, 3.7, 3.6
|
|
`PROJ`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 9.x, 8.x, 7.x, 6.x, 5.x
|
|
:doc:`GDAL <../gdal>` Geospatial Data Abstraction Library Yes 3.6, 3.5, 3.4, 3.3, 3.2, 3.1, 3.0, 2.4, 2.3, 2.2
|
|
:doc:`GeoIP <../geoip2>` IP-based geolocation library No 2
|
|
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 3.3, 3.2, 3.1, 3.0, 2.5
|
|
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 5.0, 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.6.0 2016-10-25
|
|
GEOS 3.7.0 2018-09-10
|
|
GEOS 3.8.0 2019-10-10
|
|
GEOS 3.9.0 2020-12-14
|
|
GEOS 3.10.0 2021-10-20
|
|
GEOS 3.11.0 2022-07-01
|
|
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
|
|
GDAL 3.2.0 2020-11-02
|
|
GDAL 3.3.0 2021-05-03
|
|
GDAL 3.4.0 2021-11-04
|
|
GDAL 3.5.0 2022-05-13
|
|
GDAL 3.6.0 2022-11-03
|
|
PostGIS 2.5.0 2018-09-23
|
|
PostGIS 3.0.0 2019-10-20
|
|
PostGIS 3.1.0 2020-12-18
|
|
PostGIS 3.2.0 2021-12-18
|
|
PostGIS 3.3.0 2022-08-27
|
|
PROJ 9.0.0 2022-03-01
|
|
PROJ 8.0.0 2021-03-01
|
|
PROJ 8.0.0 2021-03-01
|
|
PROJ 7.0.0 2020-02-25
|
|
PROJ 6.0.0 2019-02-26
|
|
PROJ 5.0.0 2018-03-01
|
|
SpatiaLite 4.3.0 2015-09-07
|
|
SpatiaLite 5.0.0 2020-08-23
|
|
|
|
.. 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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ wget https://download.osgeo.org/geos/geos-X.Y.Z.tar.bz2
|
|
$ tar xjf geos-X.Y.Z.tar.bz2
|
|
|
|
Then step into the GEOS directory, create a ``build`` folder, and step into
|
|
it:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cd geos-X.Y.Z
|
|
$ mkdir build
|
|
$ cd build
|
|
|
|
Then build and install the package:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cmake -DCMAKE_BUILD_TYPE=Release ..
|
|
$ cmake --build .
|
|
$ sudo cmake --build . --target install
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ wget https://download.osgeo.org/proj/proj-X.Y.Z.tar.gz
|
|
|
|
... and datum shifting files (download ``proj-datumgrid-X.Y.tar.gz`` for
|
|
PROJ < 7.x) [#]_:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ wget https://download.osgeo.org/proj/proj-data-X.Y.tar.gz
|
|
|
|
Next, untar the source code archive, and extract the datum shifting files in the
|
|
``data`` subdirectory (use ``nad`` subdirectory for PROJ < 6.x). This must be
|
|
done *prior* to configuration:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ tar xzf proj-X.Y.Z.tar.gz
|
|
$ cd proj-X.Y.Z/data
|
|
$ tar xzf ../../proj-data-X.Y.tar.gz
|
|
$ cd ../..
|
|
|
|
For PROJ 9.x and greater, releases only support builds using ``CMake`` (see
|
|
`PROJ RFC-7`_).
|
|
|
|
To build with ``CMake`` ensure your system meets the `build requirements`_.
|
|
Then create a ``build`` folder in the PROJ directory, and step into it:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cd proj-X.Y.Z
|
|
$ mkdir build
|
|
$ cd build
|
|
|
|
Finally, configure, make and install PROJ:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cmake ..
|
|
$ cmake --build .
|
|
$ sudo cmake --build . --target install
|
|
|
|
.. _PROJ RFC-7: https://proj.org/community/rfc/rfc-7.html#rfc7
|
|
.. _build requirements: https://proj.org/install.html#build-requirements
|
|
|
|
.. _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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ wget https://download.osgeo.org/gdal/X.Y.Z/gdal-X.Y.Z.tar.gz
|
|
$ tar xzf gdal-X.Y.Z.tar.gz
|
|
|
|
For GDAL 3.6.x and greater, releases only support builds using ``CMake``. To
|
|
build with ``CMake`` create a ``build`` folder in the GDAL directory, and step
|
|
into it:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cd gdal-X.Y.Z
|
|
$ mkdir build
|
|
$ cd build
|
|
|
|
Finally, configure, make and install GDAL:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ cmake ..
|
|
$ cmake --build .
|
|
$ sudo cmake --build . --target install
|
|
|
|
If you have any problems, please see the troubleshooting section below for
|
|
suggestions and solutions.
|
|
|
|
__ https://gdal.org/
|
|
|
|
.. _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:
|
|
|
|
.. code-block:: shell
|
|
|
|
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.
|