# Django 1.8.18.dev20170123152445 documentation

# Installing Spatialite

SpatiaLite adds spatial support to SQLite, turning it into a full-featured spatial database.

Check first if you can install Spatialite from system packages or binaries. For example, on Debian-based distributions, try to install the `spatialite-bin` package. For Mac OS X, follow the specific instructions below. For Windows, you may find binaries on Gaia-SINS home page. In any case, you should always be able to install from source.

When you are done with the installation process, skip to Creating a spatial database for SpatiaLite.

## Installing from source

GEOS and PROJ.4 should be installed prior to building SpatiaLite.

### SQLite

Check first if SQLite is compiled with the R*Tree module. Run the sqlite3 command line interface and enter the following query:

    sqlite> CREATE VIRTUAL TABLE testrtree USING rtree(id,minX,maxX,minY,maxY);

If you obtain an error, you will have to recompile SQLite from source. Otherwise, just skip this section.

To install from sources, download the latest amalgamation source archive from the SQLite download page, and extract:

    $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
    $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
    $ cd sqlite-3.6.23.1

Next, run the `configure` script – however the `CFLAGS` environment variable needs to be customized so that SQLite knows to build the R*Tree module:

    $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
    $ make
    $ sudo make install
    $ cd ..

### SpatiaLite library (`libspatialite`)

Get the latest SpatiaLite library source bundle from the download page:

    $ wget http://www.gaia-gis.it/gaia-sins/libspatialite-sources/libspatialite-4.1.0.tar.gz
    $ tar xaf libspatialite-4.1.0.tar.gz
    $ cd libspatialite-4.1.0
    $ ./configure
    $ make
    $ sudo make install

Note

For Mac OS X users building from source, the SpatiaLite library and tools need to have their `target` configured:

    $ ./configure --target=macosx

### pysqlite2

If you’ve decided to use a newer version of pysqlite2 instead of the `sqlite3` Python stdlib module, then you need to make sure it can load external extensions (i.e. the required `enable_load_extension` method is available so `SpatiaLite` can be loaded).

This might involve building it yourself. For this, download pysqlite2 2.6, and untar:

    $ wget https://pypi.python.org/packages/source/p/pysqlite/pysqlite-2.6.3.tar.gz
    $ tar xzf pysqlite-2.6.3.tar.gz
    $ cd pysqlite-2.6.3

Next, use a text editor to edit the `setup.cfg` file to look like the following:

    [build_ext]
    #define=
    include_dirs=/usr/local/include
    library_dirs=/usr/local/lib
    libraries=sqlite3
    #define=SQLITE_OMIT_LOAD_EXTENSION

or if you are on Mac OS X:

    [build_ext]
    #define=
    include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
    library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
    libraries=sqlite3
    #define=SQLITE_OMIT_LOAD_EXTENSION

Note

The important thing here is to make sure you comment out the `define=SQLITE_OMIT_LOAD_EXTENSION` flag and that the `include_dirs` and `library_dirs` settings are uncommented and set to the appropriate path if the SQLite header files and libraries are not in `/usr/include` and `/usr/lib`, respectively.

After modifying `setup.cfg` appropriately, then run the `setup.py` script to build and install:

    $ python setup.py install

## Mac OS X-specific instructions

To install the SpatiaLite library and tools, Mac OS X users can choose between KyngChaos packages and Homebrew.

### KyngChaos

First, follow the instructions in the KyngChaos packages section.

When Creating a spatial database for SpatiaLite, the `spatialite` program is required. However, instead of attempting to compile the SpatiaLite tools from source, download the SpatiaLite Binaries for OS X, and install `spatialite` in a location available in your `PATH`. For example:

    $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
    $ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
    $ cd spatialite-tools-osx-x86-2.3.1/bin
    $ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs

Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library, add the following to your `settings.py`:

    SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'

### Homebrew

Homebrew handles all the SpatiaLite related packages on your behalf, including SQLite3, SpatiaLite, PROJ, and GEOS. Install them like this:

    $ brew update
    $ brew install spatialite-tools
    $ brew install gdal

Finally, for GeoDjango to be able to find the SpatiaLite library, add the following to your `settings.py`:

    SPATIALITE_LIBRARY_PATH='/usr/local/lib/mod_spatialite.dylib'

## Creating a spatial database for SpatiaLite

When running `manage.py migrate` with a SQLite or SpatiaLite database, the database file will be automatically created if it doesn’t exist. Django will also ensure that the spatial metadata are initialized in the database.

Prior to Django 1.8, you had to initialize spatial metadata tables yourself by manually running the “SELECT InitSpatialMetaData();” query.