11 In general, GeoDjango installation requires:
13 1. :ref:`Python and Django <django>`
14 2. :ref:`spatial_database`
15 3. :ref:`geospatial_libs`
17 Details for each of the requirements and installation instructions
18 are provided in the sections below. In addition, platform-specific
19 instructions are available for:
25 .. admonition:: Use the Source
27 Because GeoDjango takes advantage of the latest in the open source geospatial
28 software technology, recent versions of the libraries are necessary.
29 If binary packages aren't available for your platform,
30 :ref:`installation from source <build_from_source>`
31 may be required. When compiling the libraries from source, please follow the
32 directions closely, especially if you're a beginner.
42 Because GeoDjango is included with Django, please refer to Django's
43 :ref:`installation instructions <installing-official-release>` for details on
51 PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
52 the spatial databases currently supported.
56 PostGIS is recommended, because it is the most mature and feature-rich
57 open source spatial database.
59 The geospatial libraries required for a GeoDjango installation depends
60 on the spatial database used. The following lists the library requirements,
61 supported versions, and any notes for each of the supported database backends:
63 ================== ============================== ================== ==========================================================
64 Database Library Requirements Supported Versions Notes
65 ================== ============================== ================== ==========================================================
66 PostgreSQL GEOS, PROJ.4, PostGIS 8.1+ Requires PostGIS.
67 MySQL GEOS 5.x Not OGC-compliant; limited functionality.
68 Oracle GEOS 10.2, 11 XE not supported; not tested with 9.
69 SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.
70 ================== ============================== ================== ==========================================================
76 GeoDjango uses and/or provides interfaces for the following open source
79 ======================== ==================================== ================================ ==========================
80 Program Description Required Supported Versions
81 ======================== ==================================== ================================ ==========================
82 :ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.3, 3.2, 3.1, 3.0
83 `PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.7, 4.6, 4.5, 4.4
84 :ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.8, 1.7, 1.6, 1.5, 1.4
85 :ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4
86 `PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 1.5, 1.4, 1.3
87 `SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 3.0, 2.4, 2.3
88 ======================== ==================================== ================================ ==========================
90 .. admonition:: Install GDAL
92 While :ref:`gdalbuild` is technically not required, it is *recommended*.
93 Important features of GeoDjango (including the :ref:`ref-layermapping`,
94 geometry reprojection, and the geographic admin) depend on its
99 The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
100 independently of Django. In other words, no database or settings file
101 required -- just import them as normal from :mod:`django.contrib.gis`.
103 .. _PROJ.4: http://trac.osgeo.org/proj/
104 __ http://postgis.refractions.net/
105 __ http://www.gaia-gis.it/gaia-sins/
107 .. _build_from_source:
112 When installing from source on UNIX and GNU/Linux systems, please follow
113 the installation instructions carefully, and install the libraries in the
114 given order. If using MySQL or Oracle as the spatial database, only GEOS
119 On Linux platforms, it may be necessary to run the ``ldconfig``
120 command after installing each library. For example::
127 OS X users are required to install `Apple Developer Tools`_ in order
128 to compile software from source. This is typically included on your
129 OS X installation DVDs.
131 .. _Apple Developer Tools: https://developer.apple.com/technologies/tools/
138 GEOS is a C++ library for performing geometric operations, and is the default
139 internal geometry representation used by GeoDjango (it's behind the "lazy"
140 geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``)
141 directly from Python using ctypes.
143 First, download GEOS 3.2 from the refractions Web site and untar the source
146 $ wget http://download.osgeo.org/geos/geos-3.3.0.tar.bz2
147 $ tar xjf geos-3.3.0.tar.bz2
149 Next, change into the directory where GEOS was unpacked, run the configure
150 script, compile, and install::
161 Can't find GEOS library
162 ~~~~~~~~~~~~~~~~~~~~~~~
164 When GeoDjango can't find GEOS, this error is raised:
168 ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
170 The most common solution is to properly configure your :ref:`libsettings` *or* set
171 :ref:`geoslibrarypath` in your settings.
173 If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`.
177 ``GEOS_LIBRARY_PATH``
178 ~~~~~~~~~~~~~~~~~~~~~
180 If your GEOS library is in a non-standard location, or you don't want to
181 modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
182 setting may be added to your Django settings file with the full path to the
183 GEOS C library. For example:
185 .. code-block:: python
187 GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
191 The setting must be the *full* path to the **C** shared library; in
192 other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
194 See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
201 `PROJ.4`_ is a library for converting geospatial data to different coordinate
204 First, download the PROJ.4 source code and datum shifting files [#]_::
206 $ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz
207 $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip
209 Next, untar the source code archive, and extract the datum shifting files in the
210 ``nad`` subdirectory. This must be done *prior* to configuration::
212 $ tar xzf proj-4.7.0.tar.gz
214 $ unzip ../../proj-datumgrid-1.5.zip
217 Finally, configure, make and install PROJ.4::
229 `PostGIS`__ adds geographic object support to PostgreSQL, turning it
230 into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be
231 installed prior to building PostGIS.
235 The `psycopg2`_ module is required for use as the database adaptor
236 when using GeoDjango with PostGIS.
238 .. _psycopg2: http://initd.org/psycopg/
240 First download the source archive, and extract::
242 $ wget http://postgis.refractions.net/download/postgis-1.5.2.tar.gz
243 $ tar xzf postgis-1.5.2.tar.gz
246 Next, configure, make and install PostGIS::
250 Finally, make and install::
258 GeoDjango does not automatically create a spatial database. Please
259 consult the section on :ref:`spatialdb_template` for more information.
261 __ http://postgis.refractions.net/
268 `GDAL`__ is an excellent open source geospatial library that has support for
269 reading most vector and raster spatial data formats. Currently, GeoDjango only
270 supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
271 :ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
273 First download the latest GDAL release version and untar the archive::
275 $ wget http://download.osgeo.org/gdal/gdal-1.8.1.tar.gz
276 $ tar xzf gdal-1.8.1.tar.gz
279 Configure, make and install::
282 $ make # Go get some coffee, this takes a while.
288 Because GeoDjango has it's own Python interface, the preceding instructions
289 do not build GDAL's own Python bindings. The bindings may be built by
290 adding the ``--with-python`` flag when running ``configure``. See
291 `GDAL/OGR In Python`__ for more information on GDAL's bindings.
293 If you have any problems, please see the troubleshooting section below for
294 suggestions and solutions.
296 __ http://trac.osgeo.org/gdal/
297 __ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython
304 Can't find GDAL library
305 ~~~~~~~~~~~~~~~~~~~~~~~
307 When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
310 .. code-block:: pycon
312 >>> from django.contrib.gis import gdal
316 The solution is to properly configure your :ref:`libsettings` *or* set
317 :ref:`gdallibrarypath` in your settings.
321 ``GDAL_LIBRARY_PATH``
322 ~~~~~~~~~~~~~~~~~~~~~
324 If your GDAL library is in a non-standard location, or you don't want to
325 modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
326 setting may be added to your Django settings file with the full path to
327 the GDAL library. For example:
329 .. code-block:: python
331 GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
335 Can't find GDAL data files (``GDAL_DATA``)
336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
338 When installed from source, GDAL versions 1.5.1 and below have an autoconf bug
339 that places data in the wrong location. [#]_ This can lead to error messages
344 ERROR 4: Unable to open EPSG support file gcs.csv.
346 OGRException: OGR failure.
348 The solution is to set the ``GDAL_DATA`` environment variable to the location of the
349 GDAL data files before invoking Python (typically ``/usr/local/share``; use
350 ``gdal-config --datadir`` to find out). For example::
352 $ export GDAL_DATA=`gdal-config --datadir`
353 $ python manage.py shell
355 If using Apache, you may need to add this environment variable to your configuration
358 .. code-block:: apache
360 SetEnv GDAL_DATA /usr/local/share
369 Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,
370 as it is much easier than building from source.
372 `SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
373 spatial database. Because SpatiaLite has special requirements, it typically
374 requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from
375 source. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building
378 After installation is complete, don't forget to read the post-installation
379 docs on :ref:`create_spatialite_db`.
381 __ http://www.gaia-gis.it/gaia-sins/
388 Typically, SQLite packages are not compiled to include the `R*Tree module`__ --
389 thus it must be compiled from source. First download the latest amalgamation
390 source archive from the `SQLite download page`__, and extract::
392 $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
393 $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
396 Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable
397 needs to be customized so that SQLite knows to build the R*Tree module::
399 $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
406 If using Ubuntu, installing a newer SQLite from source can be very difficult
407 because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which
408 many other packages depend on. Unfortunately, the best solution at this time
409 is to overwrite the existing library by adding ``--prefix=/usr`` to the
410 ``configure`` command.
412 __ http://www.sqlite.org/rtree.html
413 __ http://www.sqlite.org/download.html
415 .. _spatialitebuild :
417 SpatiaLite library (``libspatialite``) and tools (``spatialite``)
418 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
420 After SQLite has been built with the R*Tree module enabled, get the latest
421 SpatiaLite library source and tools bundle from the `download page`__::
423 $ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz
424 $ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz
425 $ tar xzf libspatialite-amalgamation-2.3.1.tar.gz
426 $ tar xzf spatialite-tools-2.3.1.tar.gz
428 Prior to attempting to build, please read the important notes below to see if
429 customization of the ``configure`` command is necessary. If not, then run the
430 ``configure`` script, make, and install for the SpatiaLite library::
432 $ cd libspatialite-amalgamation-2.3.1
433 $ ./configure # May need to modified, see notes below.
438 Finally, do the same for the SpatiaLite tools::
440 $ cd spatialite-tools-2.3.1
441 $ ./configure # May need to modified, see notes below.
448 If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
449 their paths when running the ``configure`` scripts for *both* the library and the
450 tools (the configure scripts look, by default, in ``/usr/local``). For example,
451 on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::
453 $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib
457 For Mac OS X users building from source, the SpatiaLite library *and* tools
458 need to have their ``target`` configured::
460 $ ./configure --target=macosx
462 __ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
469 Because SpatiaLite must be loaded as an external extension, it requires the
470 ``enable_load_extension`` method, which is only available in versions 2.5+.
471 Thus, download pysqlite2 2.6, and untar::
473 $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz
474 $ tar xzf pysqlite-2.6.0.tar.gz
477 Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
478 to look like the following:
484 include_dirs=/usr/local/include
485 library_dirs=/usr/local/lib
487 #define=SQLITE_OMIT_LOAD_EXTENSION
491 The important thing here is to make sure you comment out the
492 ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
493 and ``library_dirs`` settings are uncommented and set to the appropriate
494 path if the SQLite header files and libraries are not in ``/usr/include``
495 and ``/usr/lib``, respectively.
497 After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
498 to build and install::
500 $ sudo python setup.py install
505 .. _spatialdb_template:
507 Creating a spatial database template for PostGIS
508 ------------------------------------------------
510 Creating a spatial database with PostGIS is different than normal because
511 additional SQL must be loaded to enable spatial functionality. Because of
512 the steps in this process, it's better to create a database template that
515 First, you need to be able to execute the commands as a privileged database
516 user. For example, you can use the following to become the ``postgres`` user::
522 The location *and* name of the PostGIS SQL files (e.g., from
523 ``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
524 PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
525 whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
526 version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
528 To complicate matters, :ref:`ubuntudebian` distributions have their
529 own separate directory naming system that changes each release.
531 The example below assumes PostGIS 1.5, thus you may need to modify
532 ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific
533 version of PostGIS you are using.
535 Once you're a database super user, then you may execute the following commands
536 to create a PostGIS spatial database template::
538 $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
539 # Creating the template spatial database.
540 $ createdb -E UTF8 template_postgis
541 $ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
542 # Allows non-superusers the ability to create from this template
543 $ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
544 # Loading the PostGIS SQL routines
545 $ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
546 $ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
547 # Enabling users to alter spatial tables.
548 $ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
549 $ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
550 $ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
552 These commands may be placed in a shell script for later use; for convenience
553 the following scripts are available:
555 =============== =============================================
556 PostGIS version Bash shell script
557 =============== =============================================
558 1.3 :download:`create_template_postgis-1.3.sh`
559 1.4 :download:`create_template_postgis-1.4.sh`
560 1.5 :download:`create_template_postgis-1.5.sh`
561 Debian/Ubuntu :download:`create_template_postgis-debian.sh`
562 =============== =============================================
564 Afterwards, you may create a spatial database by simply specifying
565 ``template_postgis`` as the template to use (via the ``-T`` option)::
567 $ createdb -T template_postgis <db name>
571 While the ``createdb`` command does not require database super-user privileges,
572 it must be executed by a database user that has permissions to create databases.
573 You can create such a user with the following command::
575 $ createuser --createdb <user>
577 .. _create_spatialite_db:
579 Creating a spatial database for SpatiaLite
580 ------------------------------------------
582 After you've installed SpatiaLite, you'll need to create a number of spatial
583 metadata tables in your database in order to perform spatial queries.
585 If you're using SpatiaLite 3.0 or newer, use the ``spatialite`` utility to
586 call the ``InitSpatiaMetaData()`` function, like this::
588 $ spatialite geodjango.db "SELECT InitSpatialMetaData();"
589 the SPATIAL_REF_SYS table already contains some row(s)
590 InitSpatiaMetaData ()error:"table spatial_ref_sys already exists"
593 You can safely ignore the error messages shown. When you've done this, you can
594 skip the rest of this section.
596 If you're using a version of SpatiaLite older than 3.0, you'll need to download
597 a database-initialization file and execute its SQL queries in your database.
599 First, get it from the appropriate SpatiaLite Resources page (
600 http://www.gaia-gis.it/spatialite-2.3.1/resources.html for 2.3 or
601 http://www.gaia-gis.it/spatialite-2.4.0/ for 2.4)::
603 $ wget http://www.gaia-gis.it/spatialite-2.3.1/init_spatialite-2.3.sql.gz
604 $ gunzip init_spatialite-2.3.sql.gz
606 Then, use the ``spatialite`` command to initialize a spatial database::
608 $ spatialite geodjango.db < init_spatialite-2.X.sql
612 The parameter ``geodjango.db`` is the *filename* of the SQLite database
613 you want to use. Use the same in the :setting:`DATABASES` ``"name"`` key
614 inside your ``settings.py``.
616 Add ``django.contrib.gis`` to :setting:`INSTALLED_APPS`
617 -------------------------------------------------------
619 Like other Django contrib applications, you will *only* need to add
620 :mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings.
621 This is the so that ``gis`` templates can be located -- if not done, then
622 features such as the geographic admin or KML sitemaps will not function properly.
624 .. _addgoogleprojection:
626 Add Google projection to ``spatial_ref_sys`` table
627 --------------------------------------------------
629 .. versionchanged:: 1.2
633 If you're running PostGIS 1.4 or above, you can skip this step. The entry
634 is already included in the default ``spatial_ref_sys`` table.
636 In order to conduct database transformations to the so-called "Google"
637 projection (a spherical mercator projection used by Google Maps),
638 an entry must be added to your spatial database's ``spatial_ref_sys`` table.
639 Invoke the Django shell from your project and execute the
640 ``add_srs_entry`` function:
642 .. code-block:: pycon
644 $ python manage shell
645 >>> from django.contrib.gis.utils import add_srs_entry
646 >>> add_srs_entry(900913)
650 In Django 1.1 the name of this function is ``add_postgis_srs``.
652 This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent)
653 table, making it possible for the spatial database to transform coordinates in
654 this projection. You only need to execute this command *once* per spatial database.
659 If you can't find the solution to your problem here then participate in the
662 * Join the ``#geodjango`` IRC channel on FreeNode. Please be patient and polite
663 -- while you may not get an immediate response, someone will attempt to answer
664 your question as soon as they see it.
665 * Ask your question on the `GeoDjango`__ mailing list.
666 * File a ticket on the `Django trac`__ if you think there's a bug. Make
667 sure to provide a complete description of the problem, versions used,
668 and specify the component as "GIS".
670 __ http://groups.google.com/group/geodjango
671 __ https://code.djangoproject.com/newticket
675 Library environment settings
676 ----------------------------
678 By far, the most common problem when installing GeoDjango is that the
679 external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_
680 Typically, the cause of this problem is that the operating system isn't aware
681 of the directory where the libraries built from source were installed.
683 In general, the library path may be set on a per-user basis by setting
684 an environment variable, or by configuring the library path for the entire
687 ``LD_LIBRARY_PATH`` environment variable
688 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
690 A user may set this environment variable to customize the library paths
691 they want to use. The typical library directory for software
692 built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs
693 to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user
694 could place the following in their bash profile::
696 export LD_LIBRARY_PATH=/usr/local/lib
698 Setting system library path
699 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
701 On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
702 additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
703 As the root user, add the custom library path (like ``/usr/local/lib``) on a
704 new line in ``ld.so.conf``. This is *one* example of how to do so::
706 $ sudo echo /usr/local/lib >> /etc/ld.so.conf
709 For OpenSolaris users, the system library path may be modified using the
710 ``crle`` utility. Run ``crle`` with no options to see the current configuration
711 and use ``crle -l`` to set with the new library path. Be *very* careful when
712 modifying the system library path::
714 # crle -l $OLD_PATH:/usr/local/lib
721 GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
722 module) to discover libraries. The ``find_library`` routine uses a program
723 called ``objdump`` (part of the ``binutils`` package) to verify a shared
724 library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your
725 Linux system then Python's ctypes may not be able to find your library even if
726 your library path is set correctly and geospatial libraries were built perfectly.
728 The ``binutils`` package may be installed on Debian and Ubuntu systems using the
731 $ sudo apt-get install binutils
733 Similarly, on Red Hat and CentOS systems::
735 $ sudo yum install binutils
737 Platform-specific instructions
738 ==============================
745 Because of the variety of packaging systems available for OS X, users have
746 several different options for installing GeoDjango. These options are:
752 * :ref:`build_from_source`
756 Currently, the easiest and recommended approach for installing GeoDjango
757 on OS X is to use the KyngChaos packages.
759 This section also includes instructions for installing an upgraded version
760 of :ref:`macosx_python` from packages provided by the Python Software
761 Foundation, however, this is not required.
768 Although OS X comes with Python installed, users can use framework
769 installers (`2.5`__ and `2.6`__ are available) provided by
770 the Python Software Foundation. An advantage to using the installer is
771 that OS X's Python will remain "pristine" for internal operating system
774 __ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg
775 __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
779 You will need to modify the ``PATH`` environment variable in your
780 ``.profile`` file so that the new version of Python is used when
781 ``python`` is entered at the command-line::
783 export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
790 `Homebrew`__ provides "recipes" for building binaries and packages from source.
791 It provides recipes for the GeoDjango prerequisites on Macintosh computers
792 running OS X. Because Homebrew still builds the software from source, the
793 `Apple Developer Tools`_ are required.
797 $ brew install postgresql
798 $ brew install postgis
800 $ brew install libgeoip
802 __ http://mxcl.github.com/homebrew/
809 William Kyngesburye provides a number of `geospatial library binary packages`__
810 that make it simple to get GeoDjango installed on OS X without compiling
811 them from source. However, the `Apple Developer Tools`_ are still necessary
812 for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS)
813 and :ref:`pysqlite2_kyngchaos` (for SpatiaLite).
817 SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section
818 after installing the packages for additional instructions.
820 Download the framework packages for:
825 * SQLite3 (includes the SpatiaLite library)
828 Install the packages in the order they are listed above, as the GDAL and SQLite
829 packages require the packages listed before them. Afterwards, you can also
830 install the KyngChaos binary packages for `PostgreSQL and PostGIS`__.
832 After installing the binary packages, you'll want to add the following to
833 your ``.profile`` to be able to run the package programs from the command-line::
835 export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH
836 export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH
837 export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH
838 export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH
839 export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH
840 export PATH=/usr/local/pgsql/bin:$PATH
842 __ http://www.kyngchaos.com/software/frameworks
843 __ http://www.kyngchaos.com/software/postgres
847 Use of these binaries requires Django 1.0.3 and above. If you are
848 using a previous version of Django (like 1.0.2), then you will have
849 to add the following in your settings:
851 .. code-block:: python
853 GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS'
854 GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL'
856 .. _psycopg2_kyngchaos:
861 After you've installed the KyngChaos binaries and modified your ``PATH``, as
862 described above, ``psycopg2`` may be installed using the following command::
864 $ sudo pip install psycopg2
868 If you don't have ``pip``, follow the the :ref:`installation instructions
869 <installing-official-release>` to install it.
871 .. _pysqlite2_kyngchaos:
876 Follow the :ref:`pysqlite2` source install instructions, however,
877 when editing the ``setup.cfg`` use the following instead:
883 include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
884 library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
886 #define=SQLITE_OMIT_LOAD_EXTENSION
888 .. _spatialite_kyngchaos:
893 When :ref:`create_spatialite_db`, the ``spatialite`` program is required.
894 However, instead of attempting to compile the SpatiaLite tools from source,
895 download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a
896 location available in your ``PATH``. For example::
898 $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
899 $ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
900 $ cd spatialite-tools-osx-x86-2.3.1/bin
901 $ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs
903 Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
904 add the following to your ``settings.py``:
906 .. code-block:: python
908 SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
910 __ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
917 `Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users
918 of the `Fink`__ package system. The following packages are available, depending
919 on which version of Python you want to use:
921 * ``django-gis-py26``
922 * ``django-gis-py25``
923 * ``django-gis-py24``
925 __ http://schwehr.org/blog/
926 __ http://www.finkproject.org/
933 `MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
934 computers running OS X. Because MacPorts still builds the software from source,
935 the `Apple Developer Tools`_ are required.
939 $ sudo port install postgresql83-server
940 $ sudo port install geos
941 $ sudo port install proj
942 $ sudo port install postgis
943 $ sudo port install gdal +geos
944 $ sudo port install libgeoip
948 You will also have to modify the ``PATH`` in your ``.profile`` so
949 that the MacPorts programs are accessible from the command-line::
951 export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin
953 In addition, add the ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that
954 the libraries can be found by Python::
956 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83
958 __ http://www.macports.org/
962 Ubuntu & Debian GNU/Linux
963 -------------------------
967 The PostGIS SQL files are not placed in the PostgreSQL share directory in
968 the Debian and Ubuntu packages. Instead, they're located in a special
969 directory depending on the release. In this case, use the
970 :download:`create_template_postgis-debian.sh` script
980 In Ubuntu 11.10, PostgreSQL was upgraded to 9.1. The installation commands are:
984 $ sudo apt-get install binutils gdal-bin libproj-dev postgresql-9.1-postgis \
985 postgresql-server-dev-9.1 python-psycopg2
992 In Ubuntu 10.04, PostgreSQL was upgraded to 8.4 and GDAL was upgraded to 1.6.
993 Ubuntu 10.04 uses PostGIS 1.4, while Ubuntu 10.10 uses PostGIS 1.5 (with
994 geography support). The installation commands are:
998 $ sudo apt-get install binutils gdal-bin libproj-dev postgresql-8.4-postgis \
999 postgresql-server-dev-8.4 python-psycopg2
1006 Use the synaptic package manager to install the following packages:
1008 .. code-block:: bash
1010 $ sudo apt-get install binutils gdal-bin postgresql-8.3-postgis \
1011 postgresql-server-dev-8.3 python-psycopg2
1013 That's it! For the curious, the required binary prerequisites packages are:
1015 * ``binutils``: for ctypes to find libraries
1016 * ``postgresql-8.3``
1017 * ``postgresql-server-dev-8.3``: for ``pg_config``
1018 * ``postgresql-8.3-postgis``: for PostGIS 1.3.3
1019 * ``libgeos-3.0.0``, and ``libgeos-c1``: for GEOS 3.0.0
1020 * ``libgdal1-1.5.0``: for GDAL 1.5.0 library
1021 * ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below
1022 * ``python-psycopg2``
1024 Optional packages to consider:
1026 * ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support
1027 * ``gdal-bin``: for GDAL command line programs like ``ogr2ogr``
1028 * ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
1032 On this version of Ubuntu the ``proj`` package does not come with the
1033 datum shifting files installed, which will cause problems with the
1034 geographic admin because the ``null`` datum grid is not available for
1035 transforming geometries to the spherical mercator projection. A solution
1036 is to download the datum-shifting files, create the grid file, and
1037 install it yourself:
1039 .. code-block:: bash
1041 $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz
1044 $ tar xzf ../proj-datumgrid-1.4.tar.gz
1045 $ nad2bin null < null.lla
1046 $ sudo cp null /usr/share/proj
1048 Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you
1049 do not plan on doing any database transformation of geometries to the
1050 Google projection (900913).
1057 The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages,
1058 which is incompatible with GeoDjango. Thus, do *not* use the binary packages
1059 for GEOS or PostGIS and build some prerequisites from source, per the instructions
1060 in this document; however, it is okay to use the PostgreSQL binary packages.
1062 For more details, please see the Debian instructions for :ref:`etch` below.
1074 The situation here is the same as that of Ubuntu :ref:`heron` -- in other words,
1075 some packages must be built from source to work properly with GeoDjango.
1079 The following command will install acceptable binary packages, as well as
1080 the development tools necessary to build the rest of the requirements:
1082 .. code-block:: bash
1084 $ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 \
1085 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools
1087 Required package information:
1089 * ``binutils``: for ctypes to find libraries
1090 * ``bzip2``: for decompressing the source packages
1091 * ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries
1092 * ``flex``: required to build PostGIS
1093 * ``postgresql-8.1``
1094 * ``postgresql-server-dev-8.1``: for ``pg_config``
1095 * ``python-psycopg2``
1099 * ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support
1103 You will still have to install :ref:`geosbuild`, :ref:`proj4`,
1104 :ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the
1105 directions carefully.
1112 This version is comparable to Ubuntu :ref:`ibex`, so the command
1115 .. code-block:: bash
1117 $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 \
1118 postgresql-8.3-postgis postgresql-server-dev-8.3 \
1119 python-psycopg2 python-setuptools
1121 This assumes that you are using PostgreSQL version 8.3. Else, replace ``8.3``
1122 in the above command with the appropriate PostgreSQL version.
1126 Please read the note in the Ubuntu :ref:`ibex` install documentation
1127 about the ``proj`` package -- it also applies here because the package does
1128 not include the datum shifting files.
1132 Post-installation notes
1133 ~~~~~~~~~~~~~~~~~~~~~~~
1135 If the PostgreSQL database cluster was not initiated after installing, then it
1136 can be created (and started) with the following command:
1138 .. code-block:: bash
1140 $ sudo pg_createcluster --start 8.3 main
1142 Afterwards, the ``/etc/init.d/postgresql-8.3`` script should be used to manage
1143 the starting and stopping of PostgreSQL.
1145 In addition, the SQL files for PostGIS are placed in a different location on
1146 Debian 5.0 . Thus when :ref:`spatialdb_template` either:
1148 * Create a symbolic link to these files:
1150 .. code-block:: bash
1152 $ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql \
1153 /usr/share/postgresql/8.3
1155 If not running PostgreSQL 8.3, then replace ``8.3`` in the command above with
1156 the correct version.
1158 * Or use the :download:`create_template_postgis-debian.sh` to create the spatial database.
1165 Proceed through the following sections sequentially in order to install
1166 GeoDjango on Windows.
1170 These instructions assume that you are using 32-bit versions of
1171 all programs. While 64-bit versions of Python and PostgreSQL 9.0
1172 are available, 64-bit versions of spatial libraries, like
1173 GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
1178 First, download the latest `Python 2.7 installer`__ from the Python Web site.
1179 Next, run the installer and keep the defaults -- for example, keep
1180 'Install for all users' checked and the installation path set as
1185 You may already have a version of Python installed in ``C:\python`` as ESRI
1186 products sometimes install a copy there. *You should still install a
1187 fresh version of Python 2.7.*
1189 __ http://python.org/download/
1194 First, download the latest `PostgreSQL 9.0 installer`__ from the
1195 `EnterpriseDB`__ Web site. After downloading, simply run the installer,
1196 follow the on-screen directions, and keep the default options unless
1197 you know the consequences of changing them.
1201 The PostgreSQL installer creates both a new Windows user to be the
1202 'postgres service account' and a ``postgres`` database superuser
1203 You will be prompted once to set the password for both accounts --
1204 make sure to remember it!
1206 When the installer completes, it will ask to launch the Application Stack
1207 Builder (ASB) on exit -- keep this checked, as it is necessary to
1208 install :ref:`postgisasb`.
1212 If installed successfully, the PostgreSQL server will run in the
1213 background each time the system as started as a Windows service.
1214 A :menuselection:`PostgreSQL 9.0` start menu group will created
1215 and contains shortcuts for the ASB as well as the 'SQL Shell',
1216 which will launch a ``psql`` command window.
1218 __ http://www.enterprisedb.com/products-services-training/pgdownload
1219 __ http://www.enterprisedb.com
1226 From within the Application Stack Builder (to run outside of the installer,
1227 :menuselection:`Start --> Programs --> PostgreSQL 9.0`), select
1228 :menuselection:`PostgreSQL Database Server 9.0 on port 5432` from the drop down
1229 menu. Next, expand the :menuselection:`Categories --> Spatial Extensions` menu
1230 tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.0`.
1232 After clicking next, you will be prompted to select your mirror, PostGIS
1233 will be downloaded, and the PostGIS installer will begin. Select only the
1234 default options during install (e.g., do not uncheck the option to create a
1235 default PostGIS database).
1239 You will be prompted to enter your ``postgres`` database superuser
1240 password in the 'Database Connection Information' dialog.
1245 The ``psycopg2`` Python module provides the interface between Python and the
1246 PostgreSQL database. Download the latest `Windows installer`__ for your version
1247 of Python and PostgreSQL and run using the default settings. [#]_
1249 __ http://www.stickpeople.com/projects/python/win-psycopg/
1256 The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
1257 libraries required by GeoDjango. First, download the `OSGeo4W installer`_,
1258 and run it. Select :menuselection:`Express Web-GIS Install` and click next.
1259 In the 'Select Packages' list, ensure that GDAL is selected; MapServer and
1260 Apache are also enabled by default, but are not required by GeoDjango and
1261 may be unchecked safely. After clicking next, the packages will be
1262 automatically downloaded and installed, after which you may exit the
1265 .. _OSGeo4W installer: http://trac.osgeo.org/osgeo4w/
1267 Modify Windows environment
1268 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1270 In order to use GeoDjango, you will need to add your Python and OSGeo4W
1271 directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
1272 and ``PROJ_LIB`` environment variables. The following set of commands,
1273 executable with ``cmd.exe``, will set this up:
1277 set OSGEO4W_ROOT=C:\OSGeo4W
1278 set PYTHON_ROOT=C:\Python27
1279 set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal
1280 set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
1281 set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin
1282 reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
1283 reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
1284 reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"
1286 For your convenience, these commands are available in the executable batch
1287 script, :download:`geodjango_setup.bat`.
1291 Administrator privileges are required to execute these commands.
1292 To do this, right-click on :download:`geodjango_setup.bat` and select
1293 :menuselection:`Run as administrator`. You need to log out and log back in again
1294 for the settings to take effect.
1298 If you customized the Python or OSGeo4W installation directories,
1299 then you will need to modify the ``OSGEO4W_ROOT`` and/or ``PYTHON_ROOT``
1300 variables accordingly.
1302 Install Django and set up database
1303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1305 Finally, :ref:`install Django <installing-official-release>` on your system.
1306 You do not need to create a spatial database template, as one named
1307 ``template_postgis`` is created for you when installing PostGIS.
1309 To administer the database, you can either use the pgAdmin III program
1310 (:menuselection:`Start --> PostgreSQL 9.0 --> pgAdmin III`) or the
1311 SQL Shell (:menuselection:`Start --> PostgreSQL 9.0 --> SQL Shell`).
1312 For example, to create a ``geodjango`` spatial database and user, the following
1313 may be executed from the SQL Shell as the ``postgres`` user::
1315 postgres# CREATE USER geodjango PASSWORD 'my_passwd';
1316 postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
1318 .. rubric:: Footnotes
1319 .. [#] The datum shifting files are needed for converting data to and from
1320 certain projections.
1321 For example, the PROJ.4 string for the `Google projection (900913 or 3857)
1322 <http://spatialreference.org/ref/sr-org/6864/prj/>`_ requires the
1323 ``null`` grid file only included in the extra datum shifting files.
1324 It is easier to install the shifting files now, then to have debug a
1325 problem caused by their absence later.
1326 .. [#] Specifically, GeoDjango provides support for the `OGR
1327 <http://gdal.org/ogr>`_ library, a component of GDAL.
1328 .. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_.
1329 .. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from
1330 :mod:`ctypes.util` to locate shared libraries.
1331 .. [#] The ``psycopg2`` Windows installers are packaged and maintained by
1332 `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_.