# Django 5.2.8 documentation

# GeoDjango 安装

## 概况

一般来说，GeoDjango 安装需要：

1. Python 和 Django

2. 空间数据库

3. 地理空间库

以下各节提供了每项要求的细节和安装说明。此外，还提供了以下平台的具体说明：

- macOS

- Windows

使用源码

因为 GeoDjango 利用了最新的开源地理空间软件技术，所以需要最新版本的库。如果你的平台没有二进制包，可能需要从源码安装。当从源码编译库时，请严格按照说明进行，尤其是当你是初学者时。

## 依赖项

### Python 和 Django

因为 GeoDjango 是包含在 Django 中的，所以请参考 Django 的 安装说明 来详细了解如何安装。

### 空间数据库

目前支持的空间数据库包括 PostgreSQL（带有 PostGIS）、MySQL、Oracle 和 SQLite（带有 SpatiaLite）。

Note

推荐使用 PostGIS，因为它是最成熟、功能最丰富的开源空间数据库。

The geospatial libraries required for a GeoDjango installation depends on the spatial database used. The following lists the library requirements, supported versions, and any notes for each of the supported database backends:

数据库 | 库依赖项 | 支持的版本 | 注意
--- | --- | --- | ---
PostgreSQL | GEOS, GDAL, PROJ, PostGIS | 14+ | 需要 PostGIS。
MySQL | GEOS, GDAL | 8.0.11+ | 功能受限。
Oracle | GEOS, GDAL | 19+ | 不支持 XE。
SQLite | GEOS, GDAL, PROJ, SpatiaLite | 3.31.0+ | 需要 SpatiaLite 4.3+

关于 PostgreSQL／PostGIS／GEOS／GDAL的可能组合，也请参见 OSGeo Wiki 上的 `这个比较矩阵`__ 。

## 安装

### 地理空间库

- 安装地理空间库

### 数据库安装

- 安装 PostGIS
- 安装 SpatiaLite

### `DATABASES` 配置

将 `ENGINE` 设置为 空间后端 之一。

### 添加 `django.contrib.gis` 到 `INSTALLED_APPS`

和其他 Django contrib 应用一样，你只需要在配置中的 `INSTALLED_APPS` 中添加 `django.contrib.gis`。这是为了让 `gis` 模板能够被定位 —— 如果不这样做，那么诸如地理管理或 KML 网站地图等功能将无法正常运行。

## 错误调试

如果你在这里找不到解决问题的方法，那就参与社区吧！你可以：

- 在 `GeoDjango`__ 论坛上提出您的问题。

- File a ticket on the `Django trac`__ if you think there's a bug. Make sure to provide a complete description of the problem, versions used, and specify the component as "GIS".

### 库环境配置

到目前为止，安装 GeoDjango 时最常见的问题是无法找到外部共享库（例如 GEOS 和 GDAL）。[1] 通常情况下，造成这个问题的原因是操作系统不知道从源码建立的库的安装目录。

一般情况下，库路径可以通过设置环境变量按每个用户来设置，也可以为整个系统配置库路径。

#### `LD_LIBRARY_PATH` 环境变量

A user may set this environment variable to customize the library paths they want to use. The typical library directory for software built from source is `/usr/local/lib`. Thus, `/usr/local/lib` needs to be included in the `LD_LIBRARY_PATH` variable. For example, the user could place the following in their bash profile:

    export LD_LIBRARY_PATH=/usr/local/lib

#### 设置系统库路径

On GNU/Linux systems, there is typically a file in `/etc/ld.so.conf`, which may include additional paths from files in another directory, such as `/etc/ld.so.conf.d`. As the root user, add the custom library path (like `/usr/local/lib`) on a new line in `ld.so.conf`. This is one example of how to do so:

    $ sudo echo /usr/local/lib >> /etc/ld.so.conf
    $ sudo ldconfig

For OpenSolaris users, the system library path may be modified using the `crle` utility. Run `crle` with no options to see the current configuration and use `crle -l` to set with the new library path. Be very careful when modifying the system library path:

    # crle -l $OLD_PATH:/usr/local/lib

#### 安装 `binutils`

GeoDjango uses the `find_library` function (from the `ctypes.util` Python module) to discover libraries. The `find_library` routine uses a program called `objdump` (part of the `binutils` package) to verify a shared library on GNU/Linux systems. Thus, if `binutils` is not installed on your Linux system then Python's ctypes may not be able to find your library even if your library path is set correctly and geospatial libraries were built perfectly.

在 Debian 和 Ubuntu 系统上，可以使用以下命令安装 `binutils` 软件包：

    $ sudo apt-get install binutils

类似地，在 Red Hat 和 CentOS 系统上：

    $ sudo yum install binutils

## 特定平台说明

### macOS

由于 macOS 的打包系统多种多样，用户在安装 GeoDjango 时有几种不同的选择。这些选择是：

- Postgres.app （最简易且推荐）

- Homebrew

- Fink

- MacPorts

- 从源码构建

这一节还包含了从 Python 软件基金会提供的软件包中安装升级版 Python 的说明，但是，这不是必须的。

#### Python

Although macOS comes with Python installed, users can use `framework installers`__ provided by the Python Software Foundation. An advantage to using the installer is that macOS's Python will remain "pristine" for internal operating system use.

Note

您需要修改您的 `.profile` 文件中的 `PATH` 环境变量，以便在命令行输入 `python` 时使用新版本的 Python：

    export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH

#### Postgres.app

Postgres.app 是一个独立的 PostgreSQL 服务，包括 PostGIS 扩展。你还需要安装 `gdal` 和 `libgeoip`，并安装 Homebrew。

安装 Postgres.app 后，在你的 `.bash_profile` 中添加以下内容，这样你就可以在命令行中运行软件包的程序。用你安装的 Postgres.app 中的 PostgreSQL 版本替换 `X.Y`：

    export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/X.Y/bin

你可以在终端提示符下输入 `which psql` 检查路径是否设置正确。

#### Homebrew

`Homebrew`__ 提供了从源码中构建二进制文件和软件包的 “菜谱”。它为运行 macOS 的 Macintosh 电脑提供了 GeoDjango 的先决条件。因为 Homebrew 仍然从源码构建软件，所以需要使用 Xcode 。

摘要：

    $ brew install postgresql
    $ brew install postgis
    $ brew install gdal
    $ brew install libgeoip

##### Fink

`Kurt Schwehr`__ 很慷慨地为 `Fink`__ 包系统的用户创建了 GeoDjango 包。根据你想使用的 Python 版本，可以使用不同的包（从 `django-gis` 开始）。

#### MacPorts

`MacPorts`__ may be used to install GeoDjango prerequisites on computers running macOS. Because MacPorts still builds the software from source, Xcode is required.

摘要：

    $ sudo port install postgresql14-server
    $ sudo port install geos
    $ sudo port install proj6
    $ sudo port install postgis3
    $ sudo port install gdal
    $ sudo port install libgeoip

Note

您还需要在您的 `.profile` 中修改 `PATH`，以便从命令行访问 MacPorts 程序：

    export PATH=/opt/local/bin:/opt/local/lib/postgresql14/bin

此外，添加 `DYLD_FALLBACK_LIBRARY_PATH` 设置以便 Python 可以找到这些库：

    export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql14

### Windows

为了在 Windows 上安装 GeoDjango，请依次完成以下章节。在本教程中，我们将安装每个应用程序的 64 位版本。

#### Python

安装一个 64 位版本的 Python。更多信息请参见 安装 Python。

#### PostgreSQL

Download the latest `PostgreSQL 15.x installer`__ from the `EnterpriseDB`__ website. After downloading, run the installer, follow the on-screen directions, and keep the default options unless you know the consequences of changing them.

Note

PostgreSQL 安装程序会创建一个新的 `postgres` 数据库超级用户，你会被提示设置一次密码 —— 一定要记住它！

当安装程序完成时，它会询问 “在退出时启动 Stack Builder?” —— 请确定这个问题，因为需要安装 PostGIS。

Note

如果成功安装，每次系统启动时，PostgreSQL 服务器将作为 Windows 服务在后台运行。将创建一个 PostgreSQL 15 的开始菜单组，其中包含 Application Stack Builder (ASB) 和 'SQL Shell' 的快捷方式，后者将启动一个 `psql` 命令窗口。

#### PostGIS

在 Stack Builder 中（在安装程序外运行，选择 开始 ‣ PostgreSQL 15 ‣ Application Stack Builder），从下拉菜单中选择 PostgreSQL 15 (x64) on port 5432，然后点击下一步。展开 类别 ‣ 空间扩展 菜单树，并选择 PostGIS X.Y for PostgreSQL 15。

点击下一步后，您将被提示确认所选的包和“下载目录”。再次点击下一步，这将下载 PostGIS，并要求您点击下一步开始 PostGIS 安装程序。在安装过程中，包括四个 Yes/No 对话框，所有四个的默认选项都是 "No"。

#### OSGeo4W

The OSGeo4W installer helps to install the PROJ, GDAL, and GEOS libraries required by GeoDjango. First, download the OSGeo4W installer, and run it. Select Express Web-GIS Install and click next. In the 'Select Packages' list, ensure that GDAL is selected. If any other packages are enabled by default, they are not required by GeoDjango and may be unchecked safely. After clicking next and accepting the license agreements, the packages will be automatically downloaded and installed, after which you may exit the installer.

#### 修改 Windows 环境

In order to use GeoDjango, you will need to add your OSGeo4W directories to your Windows system `Path`, as well as create `GDAL_DATA` and `PROJ_LIB` environment variables. The following set of commands, executable with `cmd.exe`, will set this up. Restart your device once this is complete for new environment variables to be recognized:

    set OSGEO4W_ROOT=C:\OSGeo4W
    set GDAL_DATA=%OSGEO4W_ROOT%\apps\gdal\share\gdal
    set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
    set PATH=%PATH%;%OSGEO4W_ROOT%\bin
    reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
    reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
    reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"

Note

执行这些命令需要管理员权限。要做到这一点，请以管理员身份运行命令提示符，并输入上述命令。你需要注销并重新登录，设置才会生效。

Note

如果你自定义了 OSGeo4W 的安装目录，那么你需要相应地修改 `OSGEO4W_ROOT` 变量。

#### 安装 Django 并建立数据库

在您的系统上 安装 Django。建议为您创建的每个项目创建一个 虚拟环境。

#### psycopg

`psycopg` Python 模块提供了 Python 和 PostgreSQL 数据库之间的接口。您可以在 Python 虚拟环境中使用 pip 安装 `psycopg`：

    ...\> py -m pip install psycopg

脚注

[1]

GeoDjango 使用 `ctypes.util` 中的 `find_library()` 例程来查找共享库。