| 1 |
=============================== |
| 2 |
Installing Geospatial libraries |
| 3 |
=============================== |
| 4 |
|
| 5 |
GeoDjango uses and/or provides interfaces for the following open source |
| 6 |
geospatial libraries: |
| 7 |
|
| 8 |
======================== ==================================== ================================ ================================================= |
| 9 |
Program Description Required Supported Versions |
| 10 |
======================== ==================================== ================================ ================================================= |
| 11 |
:doc:`GEOS <../geos>` Geometry Engine Open Source Yes 3.13, 3.12, 3.11, 3.10, 3.9, 3.8 |
| 12 |
`PROJ`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 9.x, 8.x, 7.x, 6.x |
| 13 |
:doc:`GDAL <../gdal>` Geospatial Data Abstraction Library Yes 3.10, 3.9, 3.8, 3.7, 3.6, 3.5, 3.4, 3.3, 3.2, 3.1 |
| 14 |
:doc:`GeoIP <../geoip2>` IP-based geolocation library No 2 |
| 15 |
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 3.4, 3.3, 3.2, 3.1 |
| 16 |
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 5.1, 5.0, 4.3 |
| 17 |
======================== ==================================== ================================ ================================================= |
| 18 |
|
| 19 |
Note that older or more recent versions of these libraries *may* also work |
| 20 |
totally fine with GeoDjango. Your mileage may vary. |
| 21 |
|
| 22 |
.. |
| 23 |
Libs release dates: |
| 24 |
GEOS 3.8.0 2019-10-10 |
| 25 |
GEOS 3.9.0 2020-12-14 |
| 26 |
GEOS 3.10.0 2021-10-20 |
| 27 |
GEOS 3.11.0 2022-07-01 |
| 28 |
GEOS 3.12.0 2023-06-27 |
| 29 |
GEOS 3.13.0 2024-09-06 |
| 30 |
GDAL 3.1.0 2020-05-07 |
| 31 |
GDAL 3.2.0 2020-11-02 |
| 32 |
GDAL 3.3.0 2021-05-03 |
| 33 |
GDAL 3.4.0 2021-11-04 |
| 34 |
GDAL 3.5.0 2022-05-13 |
| 35 |
GDAL 3.6.0 2022-11-03 |
| 36 |
GDAL 3.7.0 2023-05-10 |
| 37 |
GDAL 3.8.0 2023-11-13 |
| 38 |
GDAL 3.9.0 2024-05-10 |
| 39 |
GDAL 3.10.0 2024-11-06 |
| 40 |
PostGIS 3.1.0 2020-12-18 |
| 41 |
PostGIS 3.2.0 2021-12-18 |
| 42 |
PostGIS 3.3.0 2022-08-27 |
| 43 |
PostGIS 3.4.0 2023-08-15 |
| 44 |
PROJ 9.0.0 2022-03-01 |
| 45 |
PROJ 8.0.0 2021-03-01 |
| 46 |
PROJ 8.0.0 2021-03-01 |
| 47 |
PROJ 7.0.0 2020-02-25 |
| 48 |
PROJ 6.0.0 2019-02-26 |
| 49 |
SpatiaLite 4.3.0 2015-09-07 |
| 50 |
SpatiaLite 5.0.0 2020-08-23 |
| 51 |
SpatiaLite 5.1.0 2023-08-04 |
| 52 |
|
| 53 |
.. note:: |
| 54 |
|
| 55 |
The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used |
| 56 |
independently of Django. In other words, no database or settings file |
| 57 |
required -- import them as normal from :mod:`django.contrib.gis`. |
| 58 |
|
| 59 |
.. _PROJ: https://proj.org/ |
| 60 |
__ https://postgis.net/ |
| 61 |
__ https://www.gaia-gis.it/gaia-sins/ |
| 62 |
|
| 63 |
|
| 64 |
On Debian/Ubuntu, you are advised to install the following packages which will |
| 65 |
install, directly or by dependency, the required geospatial libraries: |
| 66 |
|
| 67 |
.. code-block:: console |
| 68 |
|
| 69 |
$ sudo apt-get install binutils libproj-dev gdal-bin |
| 70 |
|
| 71 |
Please also consult platform-specific instructions if you are on :ref:`macos` |
| 72 |
or :ref:`windows`. |
| 73 |
|
| 74 |
.. _build_from_source: |
| 75 |
|
| 76 |
Building from source |
| 77 |
==================== |
| 78 |
|
| 79 |
When installing from source on UNIX and GNU/Linux systems, please follow |
| 80 |
the installation instructions carefully, and install the libraries in the |
| 81 |
given order. If using MySQL or Oracle as the spatial database, only GEOS |
| 82 |
is required. |
| 83 |
|
| 84 |
.. note:: |
| 85 |
|
| 86 |
On Linux platforms, it may be necessary to run the ``ldconfig`` command |
| 87 |
after installing each library. For example: |
| 88 |
|
| 89 |
.. code-block:: shell |
| 90 |
|
| 91 |
$ sudo make install |
| 92 |
$ sudo ldconfig |
| 93 |
|
| 94 |
.. note:: |
| 95 |
|
| 96 |
macOS users must install `Xcode`_ in order to compile software from source. |
| 97 |
|
| 98 |
.. _Xcode: https://developer.apple.com/xcode/ |
| 99 |
|
| 100 |
.. _geosbuild: |
| 101 |
|
| 102 |
GEOS |
| 103 |
---- |
| 104 |
|
| 105 |
GEOS is a C++ library for performing geometric operations, and is the default |
| 106 |
internal geometry representation used by GeoDjango (it's behind the "lazy" |
| 107 |
geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) |
| 108 |
directly from Python using ctypes. |
| 109 |
|
| 110 |
First, download GEOS from the GEOS website and untar the source archive: |
| 111 |
|
| 112 |
.. code-block:: shell |
| 113 |
|
| 114 |
$ wget https://download.osgeo.org/geos/geos-X.Y.Z.tar.bz2 |
| 115 |
$ tar xjf geos-X.Y.Z.tar.bz2 |
| 116 |
|
| 117 |
Then step into the GEOS directory, create a ``build`` folder, and step into |
| 118 |
it: |
| 119 |
|
| 120 |
.. code-block:: shell |
| 121 |
|
| 122 |
$ cd geos-X.Y.Z |
| 123 |
$ mkdir build |
| 124 |
$ cd build |
| 125 |
|
| 126 |
Then build and install the package: |
| 127 |
|
| 128 |
.. code-block:: shell |
| 129 |
|
| 130 |
$ cmake -DCMAKE_BUILD_TYPE=Release .. |
| 131 |
$ cmake --build . |
| 132 |
$ sudo cmake --build . --target install |
| 133 |
|
| 134 |
Troubleshooting |
| 135 |
~~~~~~~~~~~~~~~ |
| 136 |
|
| 137 |
Can't find GEOS library |
| 138 |
^^^^^^^^^^^^^^^^^^^^^^^ |
| 139 |
|
| 140 |
When GeoDjango can't find GEOS, this error is raised: |
| 141 |
|
| 142 |
.. code-block:: text |
| 143 |
|
| 144 |
ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings. |
| 145 |
|
| 146 |
The most common solution is to properly configure your :ref:`libsettings` *or* set |
| 147 |
:ref:`geoslibrarypath` in your settings. |
| 148 |
|
| 149 |
If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`. |
| 150 |
|
| 151 |
.. _geoslibrarypath: |
| 152 |
|
| 153 |
``GEOS_LIBRARY_PATH`` |
| 154 |
^^^^^^^^^^^^^^^^^^^^^ |
| 155 |
|
| 156 |
If your GEOS library is in a non-standard location, or you don't want to |
| 157 |
modify the system's library path then the :setting:`GEOS_LIBRARY_PATH` |
| 158 |
setting may be added to your Django settings file with the full path to the |
| 159 |
GEOS C library. For example: |
| 160 |
|
| 161 |
.. code-block:: shell |
| 162 |
|
| 163 |
GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so' |
| 164 |
|
| 165 |
.. note:: |
| 166 |
|
| 167 |
The setting must be the *full* path to the **C** shared library; in |
| 168 |
other words you want to use ``libgeos_c.so``, not ``libgeos.so``. |
| 169 |
|
| 170 |
See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`. |
| 171 |
|
| 172 |
.. _proj4: |
| 173 |
|
| 174 |
PROJ |
| 175 |
---- |
| 176 |
|
| 177 |
`PROJ`_ is a library for converting geospatial data to different coordinate |
| 178 |
reference systems. |
| 179 |
|
| 180 |
First, download the PROJ source code: |
| 181 |
|
| 182 |
.. code-block:: shell |
| 183 |
|
| 184 |
$ wget https://download.osgeo.org/proj/proj-X.Y.Z.tar.gz |
| 185 |
|
| 186 |
... and datum shifting files (download ``proj-datumgrid-X.Y.tar.gz`` for |
| 187 |
PROJ < 7.x) [#]_: |
| 188 |
|
| 189 |
.. code-block:: shell |
| 190 |
|
| 191 |
$ wget https://download.osgeo.org/proj/proj-data-X.Y.tar.gz |
| 192 |
|
| 193 |
Next, untar the source code archive, and extract the datum shifting files in the |
| 194 |
``data`` subdirectory. This must be done *prior* to configuration: |
| 195 |
|
| 196 |
.. code-block:: shell |
| 197 |
|
| 198 |
$ tar xzf proj-X.Y.Z.tar.gz |
| 199 |
$ cd proj-X.Y.Z/data |
| 200 |
$ tar xzf ../../proj-data-X.Y.tar.gz |
| 201 |
$ cd ../.. |
| 202 |
|
| 203 |
For PROJ 9.x and greater, releases only support builds using ``CMake`` (see |
| 204 |
`PROJ RFC-7`_). |
| 205 |
|
| 206 |
To build with ``CMake`` ensure your system meets the `build requirements`_. |
| 207 |
Then create a ``build`` folder in the PROJ directory, and step into it: |
| 208 |
|
| 209 |
.. code-block:: shell |
| 210 |
|
| 211 |
$ cd proj-X.Y.Z |
| 212 |
$ mkdir build |
| 213 |
$ cd build |
| 214 |
|
| 215 |
Finally, configure, make and install PROJ: |
| 216 |
|
| 217 |
.. code-block:: shell |
| 218 |
|
| 219 |
$ cmake .. |
| 220 |
$ cmake --build . |
| 221 |
$ sudo cmake --build . --target install |
| 222 |
|
| 223 |
.. _PROJ RFC-7: https://proj.org/community/rfc/rfc-7.html#rfc7 |
| 224 |
.. _build requirements: https://proj.org/install.html#build-requirements |
| 225 |
|
| 226 |
.. _gdalbuild: |
| 227 |
|
| 228 |
GDAL |
| 229 |
---- |
| 230 |
|
| 231 |
`GDAL`__ is an excellent open source geospatial library that has support for |
| 232 |
reading most vector and raster spatial data formats. Currently, GeoDjango only |
| 233 |
supports :doc:`GDAL's vector data <../gdal>` capabilities [#]_. |
| 234 |
:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL. |
| 235 |
|
| 236 |
First download the latest GDAL release version and untar the archive: |
| 237 |
|
| 238 |
.. code-block:: shell |
| 239 |
|
| 240 |
$ wget https://download.osgeo.org/gdal/X.Y.Z/gdal-X.Y.Z.tar.gz |
| 241 |
$ tar xzf gdal-X.Y.Z.tar.gz |
| 242 |
|
| 243 |
For GDAL 3.6.x and greater, releases only support builds using ``CMake``. To |
| 244 |
build with ``CMake`` create a ``build`` folder in the GDAL directory, and step |
| 245 |
into it: |
| 246 |
|
| 247 |
.. code-block:: shell |
| 248 |
|
| 249 |
$ cd gdal-X.Y.Z |
| 250 |
$ mkdir build |
| 251 |
$ cd build |
| 252 |
|
| 253 |
Finally, configure, make and install GDAL: |
| 254 |
|
| 255 |
.. code-block:: shell |
| 256 |
|
| 257 |
$ cmake .. |
| 258 |
$ cmake --build . |
| 259 |
$ sudo cmake --build . --target install |
| 260 |
|
| 261 |
If you have any problems, please see the troubleshooting section below for |
| 262 |
suggestions and solutions. |
| 263 |
|
| 264 |
__ https://gdal.org/ |
| 265 |
|
| 266 |
.. _gdaltrouble: |
| 267 |
|
| 268 |
Troubleshooting |
| 269 |
~~~~~~~~~~~~~~~ |
| 270 |
|
| 271 |
Can't find GDAL library |
| 272 |
^^^^^^^^^^^^^^^^^^^^^^^ |
| 273 |
|
| 274 |
When GeoDjango can't find the GDAL library, configure your :ref:`libsettings` |
| 275 |
*or* set :ref:`gdallibrarypath` in your settings. |
| 276 |
|
| 277 |
.. _gdallibrarypath: |
| 278 |
|
| 279 |
``GDAL_LIBRARY_PATH`` |
| 280 |
^^^^^^^^^^^^^^^^^^^^^ |
| 281 |
|
| 282 |
If your GDAL library is in a non-standard location, or you don't want to |
| 283 |
modify the system's library path then the :setting:`GDAL_LIBRARY_PATH` |
| 284 |
setting may be added to your Django settings file with the full path to |
| 285 |
the GDAL library. For example: |
| 286 |
|
| 287 |
.. code-block:: shell |
| 288 |
|
| 289 |
GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so' |
| 290 |
|
| 291 |
.. rubric:: Footnotes |
| 292 |
.. [#] The datum shifting files are needed for converting data to and from |
| 293 |
certain projections. |
| 294 |
For example, the PROJ string for the `Google projection (900913 or 3857) |
| 295 |
<https://spatialreference.org/ref/epsg/3857/>`_ requires the ``null`` |
| 296 |
grid file only included in the extra datum shifting files. It is easier |
| 297 |
to install the shifting files now, then to have debug a problem caused |
| 298 |
by their absence later. |
| 299 |
.. [#] Specifically, GeoDjango provides support for the `OGR |
| 300 |
<https://gdal.org/user/vector_data_model.html>`_ library, a component of |
| 301 |
GDAL. |