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

## 概况

一般来说，GeoDjango 安装需要：

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

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

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

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

## 依赖项

### Python 和 Django

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

### 空间数据库

目前支持的空间数据库包括 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 | 15+ | 需要 PostGIS。 |
| MySQL | GEOS, GDAL | 8.4+ | [功能受限](/zh-hans/6.1/ref/contrib/gis/db-api/#mysql-spatial-limitations)。 |
| Oracle | GEOS, GDAL | 19+ | 不支持 XE。 |
| SQLite | GEOS, GDAL, PROJ, SpatiaLite | 3.37.0+ | 需要 SpatiaLite 4.3+ |

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

## 安装

### 地理空间库

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

### 数据库安装

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

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

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

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

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

## 错误调试

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

- 在  论坛上提出您的问题。
- File a ticket on the  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:

```shell
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:

```shell
$ 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:

```shell
# 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` 软件包：

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

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

```shell
$ sudo yum install binutils
```

## 特定平台说明

### macOS

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

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

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

#### Python

Although macOS comes with Python installed, users can use  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：
>
> ```shell
> export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
> ```

#### Postgres.app

[Postgres.app](https://postgresapp.com/) is a standalone PostgreSQL server
that includes the PostGIS extension. You will also need to install `gdal`
with [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/) 。

摘要：

```shell
$ brew install postgresql
$ brew install postgis
$ brew install gdal
```

##### Fink

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

#### MacPorts

 may be used to install GeoDjango prerequisites on computers
running macOS. Because MacPorts still builds the software from source,
[Xcode](https://developer.apple.com/xcode/) is required.

摘要：

```shell
$ sudo port install postgresql15-server
$ sudo port install geos
$ sudo port install proj6
$ sudo port install postgis3
$ sudo port install gdal
```

> **Note**
>
> 您还需要在您的 `.profile` 中修改 `PATH`，以便从命令行访问 MacPorts 程序：
>
> ```shell
> export PATH=/opt/local/bin:/opt/local/lib/postgresql15/bin
> ```
>
> 此外，添加 `DYLD_FALLBACK_LIBRARY_PATH` 设置以便 Python 可以找到这些库：
>
> ```shell
> export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql15
> ```

### Windows

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

#### Python

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

#### PostgreSQL

Download the latest  from the
 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](#postgisasb)。

> **Note**
>
> If installed successfully, the PostgreSQL server will run in the background
> each time the system is started as a Windows service. A
> PostgreSQL 15 start menu group will created and contains
> shortcuts for the Application Stack Builder (ASB) as well as the
> 'SQL Shell', which will launch a `psql` command window.

#### 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](https://trac.osgeo.org/osgeo4w/) helps to install the PROJ, GDAL, and GEOS libraries
required by GeoDjango. First, download the [OSGeo4W installer](https://trac.osgeo.org/osgeo4w/), 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:

```bat
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](/zh-hans/6.1/topics/install/#installing-official-release)。建议为您创建的每个项目创建一个 [虚拟环境](https://docs.python.org/3/tutorial/venv.html)。

#### psycopg

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

```doscon
...\> py -m pip install psycopg
```

**脚注**

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