| 1 |
====================== |
| 2 |
GeoDjango Installation |
| 3 |
====================== |
| 4 |
|
| 5 |
Overview |
| 6 |
======== |
| 7 |
In general, GeoDjango installation requires: |
| 8 |
|
| 9 |
#. :ref:`Python and Django <django>` |
| 10 |
#. :ref:`spatial_database` |
| 11 |
#. :doc:`geolibs` |
| 12 |
|
| 13 |
Details for each of the requirements and installation instructions |
| 14 |
are provided in the sections below. In addition, platform-specific |
| 15 |
instructions are available for: |
| 16 |
|
| 17 |
* :ref:`macos` |
| 18 |
* :ref:`windows` |
| 19 |
|
| 20 |
.. admonition:: Use the Source |
| 21 |
|
| 22 |
Because GeoDjango takes advantage of the latest in the open source geospatial |
| 23 |
software technology, recent versions of the libraries are necessary. |
| 24 |
If binary packages aren't available for your platform, installation from |
| 25 |
source may be required. When compiling the libraries from source, please |
| 26 |
follow the directions closely, especially if you're a beginner. |
| 27 |
|
| 28 |
Requirements |
| 29 |
============ |
| 30 |
|
| 31 |
.. _django: |
| 32 |
|
| 33 |
Python and Django |
| 34 |
----------------- |
| 35 |
|
| 36 |
Because GeoDjango is included with Django, please refer to Django's |
| 37 |
:ref:`installation instructions <installing-official-release>` for details on |
| 38 |
how to install. |
| 39 |
|
| 40 |
.. _spatial_database: |
| 41 |
|
| 42 |
Spatial database |
| 43 |
---------------- |
| 44 |
PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are the |
| 45 |
spatial databases currently supported. |
| 46 |
|
| 47 |
.. note:: |
| 48 |
|
| 49 |
PostGIS is recommended, because it is the most mature and feature-rich |
| 50 |
open source spatial database. |
| 51 |
|
| 52 |
The geospatial libraries required for a GeoDjango installation depends |
| 53 |
on the spatial database used. The following lists the library requirements, |
| 54 |
supported versions, and any notes for each of the supported database backends: |
| 55 |
|
| 56 |
================== ============================== ================== ========================================= |
| 57 |
Database Library Requirements Supported Versions Notes |
| 58 |
================== ============================== ================== ========================================= |
| 59 |
PostgreSQL GEOS, GDAL, PROJ, PostGIS 14+ Requires PostGIS. |
| 60 |
MySQL GEOS, GDAL 8.0.11+ :ref:`Limited functionality <mysql-spatial-limitations>`. |
| 61 |
Oracle GEOS, GDAL 19+ XE not supported. |
| 62 |
SQLite GEOS, GDAL, PROJ, SpatiaLite 3.31.0+ Requires SpatiaLite 4.3+ |
| 63 |
================== ============================== ================== ========================================= |
| 64 |
|
| 65 |
See also `this comparison matrix`__ on the OSGeo Wiki for |
| 66 |
PostgreSQL/PostGIS/GEOS/GDAL possible combinations. |
| 67 |
|
| 68 |
__ https://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS |
| 69 |
|
| 70 |
Installation |
| 71 |
============ |
| 72 |
|
| 73 |
Geospatial libraries |
| 74 |
-------------------- |
| 75 |
|
| 76 |
.. toctree:: |
| 77 |
:maxdepth: 1 |
| 78 |
|
| 79 |
geolibs |
| 80 |
|
| 81 |
Database installation |
| 82 |
--------------------- |
| 83 |
|
| 84 |
.. toctree:: |
| 85 |
:maxdepth: 1 |
| 86 |
|
| 87 |
postgis |
| 88 |
spatialite |
| 89 |
|
| 90 |
:setting:`DATABASES` configuration |
| 91 |
---------------------------------- |
| 92 |
|
| 93 |
Set the :setting:`ENGINE <DATABASE-ENGINE>` setting to one of the :ref:`spatial |
| 94 |
backends <spatial-backends>`. |
| 95 |
|
| 96 |
Add ``django.contrib.gis`` to :setting:`INSTALLED_APPS` |
| 97 |
------------------------------------------------------- |
| 98 |
|
| 99 |
Like other Django contrib applications, you will *only* need to add |
| 100 |
:mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings. |
| 101 |
This is so that the ``gis`` templates can be located -- if not done, then |
| 102 |
features such as the geographic admin or KML sitemaps will not function properly. |
| 103 |
|
| 104 |
Troubleshooting |
| 105 |
=============== |
| 106 |
|
| 107 |
If you can't find the solution to your problem here then participate in the |
| 108 |
community! You can: |
| 109 |
|
| 110 |
* Ask your question on the `GeoDjango`__ forum. |
| 111 |
* File a ticket on the `Django trac`__ if you think there's a bug. Make |
| 112 |
sure to provide a complete description of the problem, versions used, |
| 113 |
and specify the component as "GIS". |
| 114 |
|
| 115 |
__ https://forum.djangoproject.com/c/internals/geodjango/13 |
| 116 |
__ https://code.djangoproject.com/newticket |
| 117 |
|
| 118 |
.. _libsettings: |
| 119 |
|
| 120 |
Library environment settings |
| 121 |
---------------------------- |
| 122 |
|
| 123 |
By far, the most common problem when installing GeoDjango is that the |
| 124 |
external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_ |
| 125 |
Typically, the cause of this problem is that the operating system isn't aware |
| 126 |
of the directory where the libraries built from source were installed. |
| 127 |
|
| 128 |
In general, the library path may be set on a per-user basis by setting |
| 129 |
an environment variable, or by configuring the library path for the entire |
| 130 |
system. |
| 131 |
|
| 132 |
``LD_LIBRARY_PATH`` environment variable |
| 133 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 134 |
|
| 135 |
A user may set this environment variable to customize the library paths |
| 136 |
they want to use. The typical library directory for software |
| 137 |
built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs |
| 138 |
to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user |
| 139 |
could place the following in their bash profile: |
| 140 |
|
| 141 |
.. code-block:: shell |
| 142 |
|
| 143 |
export LD_LIBRARY_PATH=/usr/local/lib |
| 144 |
|
| 145 |
Setting system library path |
| 146 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 147 |
|
| 148 |
On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include |
| 149 |
additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. |
| 150 |
As the root user, add the custom library path (like ``/usr/local/lib``) on a |
| 151 |
new line in ``ld.so.conf``. This is *one* example of how to do so: |
| 152 |
|
| 153 |
.. code-block:: shell |
| 154 |
|
| 155 |
$ sudo echo /usr/local/lib >> /etc/ld.so.conf |
| 156 |
$ sudo ldconfig |
| 157 |
|
| 158 |
For OpenSolaris users, the system library path may be modified using the |
| 159 |
``crle`` utility. Run ``crle`` with no options to see the current configuration |
| 160 |
and use ``crle -l`` to set with the new library path. Be *very* careful when |
| 161 |
modifying the system library path: |
| 162 |
|
| 163 |
.. code-block:: shell |
| 164 |
|
| 165 |
# crle -l $OLD_PATH:/usr/local/lib |
| 166 |
|
| 167 |
.. _binutils: |
| 168 |
|
| 169 |
Install ``binutils`` |
| 170 |
~~~~~~~~~~~~~~~~~~~~ |
| 171 |
|
| 172 |
GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python |
| 173 |
module) to discover libraries. The ``find_library`` routine uses a program |
| 174 |
called ``objdump`` (part of the ``binutils`` package) to verify a shared |
| 175 |
library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your |
| 176 |
Linux system then Python's ctypes may not be able to find your library even if |
| 177 |
your library path is set correctly and geospatial libraries were built perfectly. |
| 178 |
|
| 179 |
The ``binutils`` package may be installed on Debian and Ubuntu systems using the |
| 180 |
following command: |
| 181 |
|
| 182 |
.. code-block:: shell |
| 183 |
|
| 184 |
$ sudo apt-get install binutils |
| 185 |
|
| 186 |
Similarly, on Red Hat and CentOS systems: |
| 187 |
|
| 188 |
.. code-block:: shell |
| 189 |
|
| 190 |
$ sudo yum install binutils |
| 191 |
|
| 192 |
Platform-specific instructions |
| 193 |
============================== |
| 194 |
|
| 195 |
.. _macos: |
| 196 |
|
| 197 |
macOS |
| 198 |
----- |
| 199 |
|
| 200 |
Because of the variety of packaging systems available for macOS, users have |
| 201 |
several different options for installing GeoDjango. These options are: |
| 202 |
|
| 203 |
* :ref:`postgresapp` (easiest and recommended) |
| 204 |
* :ref:`homebrew` |
| 205 |
* :ref:`fink` |
| 206 |
* :ref:`macports` |
| 207 |
* :ref:`build_from_source` |
| 208 |
|
| 209 |
This section also includes instructions for installing an upgraded version |
| 210 |
of :ref:`macos_python` from packages provided by the Python Software |
| 211 |
Foundation, however, this is not required. |
| 212 |
|
| 213 |
.. _macos_python: |
| 214 |
|
| 215 |
Python |
| 216 |
~~~~~~ |
| 217 |
|
| 218 |
Although macOS comes with Python installed, users can use `framework |
| 219 |
installers`__ provided by the Python Software Foundation. An advantage to |
| 220 |
using the installer is that macOS's Python will remain "pristine" for internal |
| 221 |
operating system use. |
| 222 |
|
| 223 |
__ https://www.python.org/ftp/python/ |
| 224 |
|
| 225 |
.. note:: |
| 226 |
|
| 227 |
You will need to modify the ``PATH`` environment variable in your |
| 228 |
``.profile`` file so that the new version of Python is used when |
| 229 |
``python`` is entered at the command-line: |
| 230 |
|
| 231 |
.. code-block:: shell |
| 232 |
|
| 233 |
export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH |
| 234 |
|
| 235 |
.. _postgresapp: |
| 236 |
|
| 237 |
Postgres.app |
| 238 |
~~~~~~~~~~~~ |
| 239 |
|
| 240 |
`Postgres.app <https://postgresapp.com/>`_ is a standalone PostgreSQL server |
| 241 |
that includes the PostGIS extension. You will also need to install ``gdal`` and |
| 242 |
``libgeoip`` with :ref:`homebrew`. |
| 243 |
|
| 244 |
After installing Postgres.app, add the following to your ``.bash_profile`` so |
| 245 |
you can run the package's programs from the command-line. Replace ``X.Y`` with |
| 246 |
the version of PostgreSQL in the Postgres.app you installed: |
| 247 |
|
| 248 |
.. code-block:: bash |
| 249 |
|
| 250 |
export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/X.Y/bin |
| 251 |
|
| 252 |
You can check if the path is set up correctly by typing ``which psql`` at a |
| 253 |
terminal prompt. |
| 254 |
|
| 255 |
.. _homebrew: |
| 256 |
|
| 257 |
Homebrew |
| 258 |
~~~~~~~~ |
| 259 |
|
| 260 |
`Homebrew`__ provides "recipes" for building binaries and packages from source. |
| 261 |
It provides recipes for the GeoDjango prerequisites on Macintosh computers |
| 262 |
running macOS. Because Homebrew still builds the software from source, `Xcode`_ |
| 263 |
is required. |
| 264 |
|
| 265 |
Summary: |
| 266 |
|
| 267 |
.. code-block:: shell |
| 268 |
|
| 269 |
$ brew install postgresql |
| 270 |
$ brew install postgis |
| 271 |
$ brew install gdal |
| 272 |
$ brew install libgeoip |
| 273 |
|
| 274 |
__ https://brew.sh/ |
| 275 |
.. _Xcode: https://developer.apple.com/xcode/ |
| 276 |
|
| 277 |
.. _fink: |
| 278 |
|
| 279 |
Fink |
| 280 |
^^^^ |
| 281 |
|
| 282 |
`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users |
| 283 |
of the `Fink`__ package system. `Different packages are available`__ (starting |
| 284 |
with ``django-gis``), depending on which version of Python you want to use. |
| 285 |
|
| 286 |
__ https://schwehr.blogspot.com/ |
| 287 |
__ https://www.finkproject.org/ |
| 288 |
__ https://pdb.finkproject.org/pdb/browse.php?summary=django-gis |
| 289 |
|
| 290 |
.. _macports: |
| 291 |
|
| 292 |
MacPorts |
| 293 |
~~~~~~~~ |
| 294 |
|
| 295 |
`MacPorts`__ may be used to install GeoDjango prerequisites on computers |
| 296 |
running macOS. Because MacPorts still builds the software from source, |
| 297 |
`Xcode`_ is required. |
| 298 |
|
| 299 |
Summary: |
| 300 |
|
| 301 |
.. code-block:: shell |
| 302 |
|
| 303 |
$ sudo port install postgresql14-server |
| 304 |
$ sudo port install geos |
| 305 |
$ sudo port install proj6 |
| 306 |
$ sudo port install postgis3 |
| 307 |
$ sudo port install gdal |
| 308 |
$ sudo port install libgeoip |
| 309 |
|
| 310 |
.. note:: |
| 311 |
|
| 312 |
You will also have to modify the ``PATH`` in your ``.profile`` so |
| 313 |
that the MacPorts programs are accessible from the command-line: |
| 314 |
|
| 315 |
.. code-block:: shell |
| 316 |
|
| 317 |
export PATH=/opt/local/bin:/opt/local/lib/postgresql14/bin |
| 318 |
|
| 319 |
In addition, add the ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that |
| 320 |
the libraries can be found by Python: |
| 321 |
|
| 322 |
.. code-block:: shell |
| 323 |
|
| 324 |
export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql14 |
| 325 |
|
| 326 |
__ https://www.macports.org/ |
| 327 |
|
| 328 |
.. _windows: |
| 329 |
|
| 330 |
Windows |
| 331 |
------- |
| 332 |
|
| 333 |
Proceed through the following sections sequentially in order to install |
| 334 |
GeoDjango on Windows. In this tutorial we will install 64 bit versions of each |
| 335 |
application. |
| 336 |
|
| 337 |
Python |
| 338 |
~~~~~~ |
| 339 |
|
| 340 |
Install a 64 bit version of Python. See :doc:`Install Python </howto/windows>` |
| 341 |
for further information. |
| 342 |
|
| 343 |
PostgreSQL |
| 344 |
~~~~~~~~~~ |
| 345 |
|
| 346 |
Download the latest `PostgreSQL 15.x installer`__ from the |
| 347 |
`EnterpriseDB`__ website. After downloading, run the installer, follow the |
| 348 |
on-screen directions, and keep the default options unless you know the |
| 349 |
consequences of changing them. |
| 350 |
|
| 351 |
.. note:: |
| 352 |
|
| 353 |
The PostgreSQL installer creates a new ``postgres`` database superuser |
| 354 |
You will be prompted once to set the password -- make sure to remember it! |
| 355 |
|
| 356 |
When the installer completes, it will ask to "Launch Stack Builder at exit?" -- |
| 357 |
keep this checked, as it is necessary to install :ref:`postgisasb`. |
| 358 |
|
| 359 |
.. note:: |
| 360 |
|
| 361 |
If installed successfully, the PostgreSQL server will run in the background |
| 362 |
each time the system as started as a Windows service. A |
| 363 |
:menuselection:`PostgreSQL 15` start menu group will created and contains |
| 364 |
shortcuts for the Application Stack Builder (ASB) as well as the |
| 365 |
'SQL Shell', which will launch a ``psql`` command window. |
| 366 |
|
| 367 |
__ https://www.enterprisedb.com/downloads/postgres-postgresql-downloads |
| 368 |
__ https://www.enterprisedb.com |
| 369 |
|
| 370 |
.. _postgisasb: |
| 371 |
|
| 372 |
PostGIS |
| 373 |
~~~~~~~ |
| 374 |
|
| 375 |
From within the Stack Builder (to run outside of the installer, |
| 376 |
:menuselection:`Start --> PostgreSQL 15 --> Application Stack Builder`), select |
| 377 |
:menuselection:`PostgreSQL 15 (x64) on port 5432` from the drop down |
| 378 |
menu and click next. Expand the |
| 379 |
:menuselection:`Categories --> Spatial Extensions` menu tree and select |
| 380 |
:menuselection:`PostGIS X.Y for PostgreSQL 15`. |
| 381 |
|
| 382 |
After clicking next, you will be prompted to confirm the selected package and |
| 383 |
"Download directory". Click next again, this will download PostGIS and you will |
| 384 |
be asked to click next to begin the PostGIS installer. Select the default |
| 385 |
options during install. The install process includes four Yes/No dialog boxes, |
| 386 |
the default option for all four is "No". |
| 387 |
|
| 388 |
.. _osgeo4w: |
| 389 |
|
| 390 |
OSGeo4W |
| 391 |
~~~~~~~ |
| 392 |
|
| 393 |
The `OSGeo4W installer`_ helps to install the PROJ, GDAL, and GEOS libraries |
| 394 |
required by GeoDjango. First, download the `OSGeo4W installer`_, and |
| 395 |
run it. Select :menuselection:`Express Web-GIS Install` and click next. In the |
| 396 |
'Select Packages' list, ensure that GDAL is selected. If any other packages are |
| 397 |
enabled by default, they are not required by GeoDjango and may be unchecked |
| 398 |
safely. After clicking next and accepting the license agreements, the packages |
| 399 |
will be automatically downloaded and installed, after which you may exit the |
| 400 |
installer. |
| 401 |
|
| 402 |
.. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/ |
| 403 |
|
| 404 |
Modify Windows environment |
| 405 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 406 |
|
| 407 |
In order to use GeoDjango, you will need to add your OSGeo4W |
| 408 |
directories to your Windows system ``Path``, as well as create ``GDAL_DATA`` |
| 409 |
and ``PROJ_LIB`` environment variables. The following set of commands, |
| 410 |
executable with ``cmd.exe``, will set this up. Restart your device |
| 411 |
once this is complete for new environment variables to be recognized: |
| 412 |
|
| 413 |
.. code-block:: bat |
| 414 |
|
| 415 |
set OSGEO4W_ROOT=C:\OSGeo4W |
| 416 |
set GDAL_DATA=%OSGEO4W_ROOT%\apps\gdal\share\gdal |
| 417 |
set PROJ_LIB=%OSGEO4W_ROOT%\share\proj |
| 418 |
set PATH=%PATH%;%OSGEO4W_ROOT%\bin |
| 419 |
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%" |
| 420 |
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%" |
| 421 |
reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%" |
| 422 |
|
| 423 |
.. note:: |
| 424 |
|
| 425 |
Administrator privileges are required to execute these commands. |
| 426 |
To do this, run command prompt as administrator and enter the commands |
| 427 |
above. You need to log out and log back in again for the settings to take |
| 428 |
effect. |
| 429 |
|
| 430 |
.. note:: |
| 431 |
|
| 432 |
If you customized the OSGeo4W installation directories, then you will need |
| 433 |
to modify the ``OSGEO4W_ROOT`` variables accordingly. |
| 434 |
|
| 435 |
Install Django and set up database |
| 436 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 437 |
|
| 438 |
:ref:`Install Django <installing-official-release>` on your system. It is |
| 439 |
recommended that you create a :doc:`virtual environment |
| 440 |
<python:tutorial/venv>` for each project you create. |
| 441 |
|
| 442 |
psycopg |
| 443 |
~~~~~~~ |
| 444 |
|
| 445 |
The ``psycopg`` Python module provides the interface between Python and the |
| 446 |
PostgreSQL database. ``psycopg`` can be installed via pip within your Python |
| 447 |
virtual environment: |
| 448 |
|
| 449 |
.. code-block:: doscon |
| 450 |
|
| 451 |
...\> py -m pip install psycopg |
| 452 |
|
| 453 |
.. rubric:: Footnotes |
| 454 |
.. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from |
| 455 |
``ctypes.util`` to locate shared libraries. |