Debian Codegraph @

docs/ref/contrib/gis/install/geolibs.txt

raw
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.