---
title: "GeoDjango 安装"
version: 4.1
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/4.1/ref/contrib/gis/install/
canonical: https://djangodocs.dev/zh-hans/4.1/ref/contrib/gis/install/
---
# GeoDjango 安装

## 概况

一般来说，GeoDjango 安装需要：

1. [Python 和 Django](#django)
2. [空间数据库](#spatial-database)
3. [安装地理空间库](/zh-hans/4.1/ref/contrib/gis/install/geolibs/)

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

- [macOS](#macos)
- [Windows](#windows)

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

## 依赖项

### Python 和 Django

因为 GeoDjango 是包含在 Django 中的，所以请参考 Django 的 [安装说明](/zh-hans/4.1/topics/install/#installing-official-release) 来详细了解如何安装。

### 空间数据库

PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are the
spatial databases currently supported.

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

GeoDjango 安装所需的地理空间库取决于所使用的空间数据库。 下面列出了每个支持的数据库后端的库需求、支持的版本和任何注释。

| 数据库 | 库依赖项 | 支持的版本 | 注意 |
| --- | --- | --- | --- |
| PostgreSQL | GEOS, GDAL, PROJ, PostGIS | 11+ | 需要 PostGIS。 |
| MySQL | GEOS, GDAL | 5.7+ | [功能受限](/zh-hans/4.1/ref/contrib/gis/db-api/#mysql-spatial-limitations)。 |
| Oracle | GEOS, GDAL | 19+ | 不支持 XE。 |
| SQLite | GEOS, GDAL, PROJ, SpatiaLite | 3.9.0+ | 需要 SpatiaLite 4.3+ |

关于 PostgreSQL／PostGIS／GEOS／GDAL的可能组合，也请参见 OSGeo Wiki 上的  。

## 安装

### 地理空间库

- [安装地理空间库](/zh-hans/4.1/ref/contrib/gis/install/geolibs/)

### 数据库安装

- [安装 PostGIS](/zh-hans/4.1/ref/contrib/gis/install/postgis/)
- [安装 SpatiaLite](/zh-hans/4.1/ref/contrib/gis/install/spatialite/)

### [`DATABASES`](/zh-hans/4.1/ref/settings/#std-setting-DATABASES) 配置

将 [`ENGINE`](/zh-hans/4.1/ref/settings/#std-setting-DATABASE-ENGINE) 设置为 [空间后端](/zh-hans/4.1/ref/contrib/gis/db-api/#spatial-backends) 之一。

### 添加 `django.contrib.gis` 到 [`INSTALLED_APPS`](/zh-hans/4.1/ref/settings/#std-setting-INSTALLED_APPS)

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

## 错误调试

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

- Join the `#django-geo` IRC channel on Libera.Chat. Please be patient and
  polite -- while you may not get an immediate response, someone will attempt
  to answer your question as soon as they see it.
- Ask your question on the  forum.
- 如果你认为有 bug，请在  上提交一个工单。 确保提供完整的问题描述，使用的版本，并指定组件为 “GIS”。

### 库环境配置

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

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

#### `LD_LIBRARY_PATH` 环境变量

用户可以设置这个环境变量来定制他们想要使用的库路径。 典型的从源代码构建的软件的库目录是 `/usr/local/lib`。 因此，`/usr/local/lib` 需要包含在 `LD_LIBRARY_PATH` 变量中。 例如，用户可以在其 bash 配置文件中加入以下内容：

```console
export LD_LIBRARY_PATH=/usr/local/lib
```

#### 设置系统库路径

在 GNU／Linux 系统中，通常在 `/etc/ld.so.conf` 中会有一个文件，其中可能包括来自另一个目录中的文件的附加路径，例如 `/etc/ld.so.conf.d`。作为 root 用户，在 `ld.so.conf` 中的新行中添加自定义库路径（如 `/usr/local/lib`）。 这是 *一个* 例子：

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

对于 OpenSolaris 用户，可以使用 `crle` 工具修改系统库路径。 运行 `crle` 时不要有任何选项，以查看当前的配置，并使用 `crle -l` 来设置新的库路径。 修改系统库路径时要 *非常* 小心：

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

#### 安装 `binutils`

GeoDjango 使用 `find_library` 函数（来自 `ctypes.util` Python 模块）来发现库。 `find_library` 例程使用一个叫做 `objdump` 的程序（`binutils` 包的一部分）来验证 GNU／Linux 系统的共享库。 因此，如果 `binutils` 没有安装在你的 Linux 系统上，那么 Python 的 ctypes 可能无法找到你的库，即使你的库路径设置正确，并且地理空间库建立得很完美。

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

```console
$ sudo apt-get install binutils
```

同样，在 Red Hat 和 CentOS 系统上：

```console
$ sudo yum install binutils
```

## 特定平台说明

### macOS

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

- [Postgres.app](#postgresapp) （最简易且推荐）
- [Homebrew](#homebrew)
- [Fink](#fink)
- [MacPorts](#macports)
- [从源码构建](/zh-hans/4.1/ref/contrib/gis/install/geolibs/#build-from-source)

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

#### Python

虽然 macOS 安装了 Python，但用户可以使用 Python 软件基金会提供的  。 使用安装程序的一个好处是，macOS 的 Python 将保持 “原始” 状态，供操作系统内部使用。

> **Note**
>
> 你需要修改 `.profile` 文件中的 `PATH` 环境变量，以便在命令行输入 `python` 时使用新版本的 Python：
>
> ```console
> export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
> ```

#### Postgres.app

[Postgres.app](https://postgresapp.com/) 是一个独立的 PostgreSQL 服务，包括 PostGIS 扩展。你还需要安装 `gdal` 和 `libgeoip`，并安装 [Homebrew](#homebrew)。

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

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

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

#### Homebrew

 提供了从源码中构建二进制文件和软件包的 “菜谱”。它为运行 macOS 的 Macintosh 电脑提供了 GeoDjango 的先决条件。因为 Homebrew 仍然从源码构建软件，所以需要使用 [Xcode](https://developer.apple.com/xcode/) 。

摘要：

```console
$ brew install postgresql
$ brew install postgis
$ brew install gdal
$ brew install libgeoip
```

##### Fink

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

#### MacPorts

 可以用来在运行 macOS 的计算机上安装 GeoDjango 的先决条件。 因为 MacPorts 仍然从源码构建软件，所以需要使用 [Xcode](https://developer.apple.com/xcode/) 。

摘要：

```console
$ sudo port install postgresql13-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 程序可以从命令行访问：
>
> ```console
> export PATH=/opt/local/bin:/opt/local/lib/postgresql13/bin
> ```
>
> 另外，增加 `DYLD_FALLBACK_LIBRARY_PATH` 设置，这样就可以通过 Python：
>
> ```console
> export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql13
> ```

### Windows

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

#### Python

安装一个 64 位版本的 Python。更多信息请参见 [安装 Python](/zh-hans/4.1/howto/windows/)。

#### PostgreSQL

从  网站下载最新的  。 下载后，运行安装程序，按照屏幕上的指示，保持默认选项，除非你知道改变这些选项的后果。

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

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

> **Note**
>
> 如果安装成功，PostgreSQL 服务器将在每次系统作为 Windows 服务启动时在后台运行。一个 PostgreSQL 12 开始菜单组将被创建，并包含应用程序堆栈生成器（ASB）和 “SQL Shell” 的快捷方式，它将启动一个 `psql` 命令窗口。

#### PostGIS

在堆栈生成器中（如果要在安装程序之外运行， Start ‣ PostgreSQL 12 ‣ Application Stack Builder），从下拉菜单中选择 PostgreSQL 12 (x64) on port 5432，然后点击下一步。展开 Categories ‣ Spatial Extensions 菜单树，选择 PostGIS X.Y for PostgreSQL 12。

点击下一步后，会提示你确认选择的软件包和 “下载目录”。再次点击下一步，这将下载 PostGIS，并要求你点击下一步开始 PostGIS 安装程序。在安装过程中选择默认选项。安装过程中包括三个 “是／否” 对话框，三个对话框的默认选项都是 “否”。

#### OSGeo4W

[OSGeo4W 安装程序](https://trac.osgeo.org/osgeo4w/) 有助于安装 GeoDjango 所需的 PROJ、GDAL 和 GEOS 库。首先，下载  （64 位），并运行它。选择 Express Web-GIS Install，点击下一步。 在 “Select Packages” 列表中，确保选择 GDAL；MapServer 也是默认启用的，但 GeoDjango 不需要，可以放心地取消勾选。点击下一步并接受许可协议后，包将自动下载并安装，之后可以退出安装程序。

#### 修改 Windows 环境

为了使用 GeoDjango，你需要将 OSGeo4W 目录添加到 Windows 系统的 `Path` 中，并创建 `GDAL_DATA` 和 `PROJ_LIB` 环境变量。 下面这组命令可以用 `cmd.exe` 执行，用于设置。设置完成后，请重新启动设备，以便识别新的环境变量。

```bat
set OSGEO4W_ROOT=C:\OSGeo4W64
set GDAL_DATA=%OSGEO4W_ROOT%\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**
>
> 这假设安装了 64 位版本的 OSGeo4W。如果你已经安装了 32 位版本，你需要将第一条命令改为 `set OSGEO4W_ROOT=C:\OSGeo4W`。

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

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

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

[install Django](/zh-hans/4.1/topics/install/#installing-official-release) on your system. It is
recommended that you create a [virtual environment](https://docs.python.org/3/tutorial/venv.html) for each project you create.

#### psycopg2

`psycopg2` Python 模块提供 Python 和 PostgreSQL 数据库之间的接口。`psycopg2` 可以在 Python 虚拟环境中通过 pip 安装：

```console
...\> py -m pip install psycopg2
```

**脚注**

[^1]: GeoDjango 使用 `ctypes.util` 中的 [`find_library()`](https://docs.python.org/3/library/ctypes.html#ctypes.util.find_library) 例程来查找共享库。