---
title: "安装地理空间库"
version: 5.0
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/5.0/ref/contrib/gis/install/geolibs/
canonical: https://djangodocs.dev/zh-hans/5.0/ref/contrib/gis/install/geolibs/
---
# 安装地理空间库

GeoDjango 使用和／或提供以下开源地理空间库的接口：

| 程序 | 描述 | 必须的 | 支持的版本 |
| --- | --- | --- | --- |
| [GEOS](/zh-hans/5.0/ref/contrib/gis/geos/) | 几何引擎开源 | 是 | 3.12, 3.11, 3.10, 3.9, 3.8 |
| [PROJ](https://proj.org/) | 制图投影库 | 是（仅 PostgreSQL 和 SQLite） | 9.x, 8.x, 7.x, 6.x, 5.x |
| [GDAL](/zh-hans/5.0/ref/contrib/gis/gdal/) | 地理空间数据抽象库 | 是 | 3.7, 3.6, 3.5, 3.4, 3.3, 3.2, 3.1, 3.0, 2.4 |
| [GeoIP](/zh-hans/5.0/ref/contrib/gis/geoip2/) | 基于 IP 的地理定位库 | 否 | 2 |
| [PostGIS](https://postgis.net/) | PostgreSQL 的空间扩展 | 是（仅 PostgreSQL） | 3.4, 3.3, 3.2, 3.1, 3.0, 2.5 |
| [SpatiaLite](https://www.gaia-gis.it/gaia-sins/) | SQLite 的空间扩展 | 是（仅 SQLite） | 5.1, 5.0, 4.3 |

请注意，这些库的老版本或最新版本可能也能与 GeoDjango 完全兼容。你的里程数可能会有所不同。

> **Note**
>
> GeoDjango 的 GEOS、GDAL 和 GeoIP 接口可以独立于 Django 使用。 换句话说，不需要数据库或配置文件 —— 像正常的那样从 [`django.contrib.gis`](/zh-hans/5.0/ref/contrib/gis/#module-django.contrib.gis) 导入它们。

在 Debian／Ubuntu 上，我们建议您安装以下软件包，它们将直接或通过依赖关系安装所需的地理空间库：

```console
$ sudo apt-get install binutils libproj-dev gdal-bin
```

如果你使用的是 [macOS](/zh-hans/5.0/ref/contrib/gis/install/#macos) 或 [Windows](/zh-hans/5.0/ref/contrib/gis/install/#windows)，也请参考特定平台的说明。

## 从源码构建

在 UNIX 和 GNU／Linux 系统上从源码安装时，请仔细按照安装说明，并按照给定的顺序安装库。 如果使用 MySQL 或 Oracle 作为空间数据库，则只需要 GEOS。

> **Note**
>
> 在 Linux 平台上，在安装每个库之后可能需要运行 `ldconfig` 命令。例如：
>
> ```shell
> $ sudo make install
> $ sudo ldconfig
> ```

> **Note**
>
> macOS 用户必须安装 [Xcode](https://developer.apple.com/xcode/) 才能从源码编译软件。

### GEOS

GEOS 是一个用于执行几何运算的 C++ 库，是 GeoDjango 默认使用的内部几何表示法（它的背后是 “惰性” 的几何图形）。 具体来说，在 Python 中使用 ctypes 直接调用 C API 库（如 `libgeos_c.so`）。

首先，从 GEOS 网站下载 GEOS，并解压源代码存档：

```shell
$ wget https://download.osgeo.org/geos/geos-X.Y.Z.tar.bz2
$ tar xjf geos-X.Y.Z.tar.bz2
```

然后进入 GEOS 目录，创建一个名为 `build` 的文件夹，并进入其中：

```shell
$ cd geos-X.Y.Z
$ mkdir build
$ cd build
```

然后构建并安装该软件包：

```shell
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ cmake --build .
$ sudo cmake --build . --target install
```

#### 错误调试

##### 找不到 GEOS 库

当 GeoDjango 找不到 GEOS 时，就会出现这个错误：

```text
ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
```

最常见的解决方案是正确配置你的 [库环境配置](/zh-hans/5.0/ref/contrib/gis/install/#libsettings) *或* 在你的配置中设置 [GEOS\_LIBRARY\_PATH](#geoslibrarypath)。

如果使用 GEOS 的二进制包（例如，在 Ubuntu 上），你可能需要 [安装 binutils](/zh-hans/5.0/ref/contrib/gis/install/#binutils)。

##### `GEOS_LIBRARY_PATH`

如果您的 GEOS 库位于非标准位置，或者您不想修改系统的库路径，那么可以在 Django 配置文件中添加 [`GEOS_LIBRARY_PATH`](/zh-hans/5.0/ref/contrib/gis/geos/#std-setting-GEOS_LIBRARY_PATH) 设置，其中包含 GEOS C 库的完整路径。例如：

```shell
GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
```

> **Note**
>
> 这个配置必须是 **C** 共享库的 *完整* 路径；换句话说，你要使用 `libgeos_c.so`，而不是 `libgeos.so`。

另见 [我的日志中充满了与 GEOS 有关的错误](/zh-hans/5.0/ref/contrib/gis/geos/#geos-exceptions-in-logfile)。

### PROJ

[PROJ](https://proj.org/) 是一个用于将地理空间数据转换为不同坐标参考系统的库。

首先，下载 PROJ 源代码：

```shell
$ wget https://download.osgeo.org/proj/proj-X.Y.Z.tar.gz
```

...和数据转换文件（如果使用 PROJ \< 7.x，请下载 `proj-datumgrid-X.Y.tar.gz`）\[#\]\_:

```shell
$ wget https://download.osgeo.org/proj/proj-data-X.Y.tar.gz
```

接下来，解压源代码存档，并在 `data` 子目录中提取数据转换文件（对于 PROJ \< 6.x，请使用 `nad` 子目录）。这必须在配置之前完成：

```shell
$ tar xzf proj-X.Y.Z.tar.gz
$ cd proj-X.Y.Z/data
$ tar xzf ../../proj-data-X.Y.tar.gz
$ cd ../..
```

对于 PROJ 9.x 及更高版本，发布版仅支持使用 `CMake` 进行构建（参见 [PROJ RFC-7](https://proj.org/community/rfc/rfc-7.html#rfc7)）。

要使用 `CMake` 进行构建，请确保您的系统满足 [构建要求](https://proj.org/install.html#build-requirements)。然后在 PROJ 目录中创建一个名为 `build` 的文件夹，并进入其中：

```shell
$ cd proj-X.Y.Z
$ mkdir build
$ cd build
```

最后，配置、编译和安装 PROJ：

```shell
$ cmake ..
$ cmake --build .
$ sudo cmake --build . --target install
```

### GDAL

[GDAL](https://gdal.org/) 是一个优秀的开源地理空间库，它支持读取大多数矢量和栅格空间数据格式。目前 GeoDjango 只支持 GDAL 的矢量数据 的功能 [^2] 。 在构建 GDAL 之前，应该安装 [GEOS](#geosbuild) 和 [PROJ](#proj4)。

首先下载最新版本的 GDAL 发行版并解压存档：

```shell
$ wget https://download.osgeo.org/gdal/X.Y.Z/gdal-X.Y.Z.tar.gz
$ tar xzf gdal-X.Y.Z.tar.gz
```

对于 GDAL 3.6.x 及更高版本，发布版仅支持使用 `CMake` 进行构建。要使用 `CMake` 进行构建，请在 GDAL 目录中创建一个名为 `build` 的文件夹，并进入其中：

```shell
$ cd gdal-X.Y.Z
$ mkdir build
$ cd build
```

最后，配置、编译和安装 GDAL：

```shell
$ cmake ..
$ cmake --build .
$ sudo cmake --build . --target install
```

如果你有任何问题，请参见下面的故障排除部分，以获得建议和解决方案。

#### 错误调试

##### 找不到 GDAL 库

当 GeoDjango 找不到 GDAL 库时，在你的配置中设置你的 [库环境配置](/zh-hans/5.0/ref/contrib/gis/install/#libsettings) *或* [GDAL\_LIBRARY\_PATH](#gdallibrarypath)。

##### `GDAL_LIBRARY_PATH`

如果您的 GDAL 库位于非标准位置，或者您不想修改系统的库路径，那么可以在 Django 配置文件中添加 [`GDAL_LIBRARY_PATH`](/zh-hans/5.0/ref/contrib/gis/gdal/#std-setting-GDAL_LIBRARY_PATH) 设置，其中包含 GDAL 库的完整路径。例如：

```shell
GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
```

**脚注**

[^1]: 这些数据转换文件用于将数据转换到某些投影中以及从某些投影中进行转换。例如，用于 [Google 投影 (900913 或 3857)](https://spatialreference.org/ref/epsg/3857/) 的 PROJ 字符串需要仅包含在额外数据转换文件中的 `null` 网格文件。现在安装这些转换文件会更容易，而不是以后因其缺失而导致问题时再进行调试。

[^2]: 具体来说，GeoDjango 提供了对 [OGR](https://gdal.org/user/vector_data_model.html) 库的支持，这是 GDAL 的一个组件。