OSMnx在NVIDIA Jetson (aarch64) 环境安装完整指南

从零开始在ARM架构设备上搭建OSMnx地理数据处理环境，踩坑实录与完整解决方案

📌 前言

最近在做一个项目，需要在NVIDIA Jetson设备上使用OSMnx（OpenStreetMap eXtraction）库来获取道路数据。本以为只是一个简单的 pip install，结果却踩了一连串的坑，折腾了整整一天。特此记录，希望能帮助到同样在aarch64架构上折腾OSMnx的朋友。

环境信息

📦 第一关：Fiona安装失败 - 缺少GDAL

问题现象

执行 pip install osmnx 时出现以下错误：

nvidia@pc:~$ pip install osmnx
Collecting osmnx
  Downloading osmnx-1.9.4-py3-none-any.whl (107 kB)
Collecting fiona>=1.8.19
  Downloading fiona-1.10.1.tar.gz (444 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  ERROR: Command errored out with exit status 1:
   command: /usr/bin/python3 /tmp/tmpl1okb5v0 get_requires_for_build_wheel /tmp/tmpkafq2rqa
       cwd: /tmp/pip-install-a4qf_y58/fiona
  Complete output (2 lines):
  WARNING:root:Failed to get options via gdal-config: [Errno 2] No such file or directory: 'gdal-config'
  CRITICAL:root:A GDAL API version must be specified.

原因分析

fiona 是 geopandas 的核心依赖，用于读写地理空间数据。它在安装时需要编译C++扩展，因此必须依赖系统的GDAL（Geospatial Data Abstraction Library）开发库。系统默认没有安装GDAL，导致编译失败。

解决方案

安装GDAL开发库及Python绑定：

# 更新包列表
sudo apt update

# 安装GDAL及相关开发库
sudo apt install gdal-bin libgdal-dev python3-gdal

# 设置环境变量，指定gdal-config路径
export GDAL_CONFIG=/usr/bin/gdal-config

# 重新尝试安装
pip install osmnx

经验总结

💡 关键点：pip install 某些地理信息库时，需要先安装系统级依赖。对于地理空间相关的Python库（fiona、shapely、pyproj、rasterio等），通常需要提前安装GDAL、GEOS、PROJ等底层库。

🔄 第二关：GDAL版本不兼容

问题现象

安装完GDAL后再次尝试，出现了新错误：

nvidia@pc:~$ export GDAL_CONFIG=/usr/bin/gdal-config
nvidia@pc:~$ pip install osmnx

Collecting fiona>=1.8.19
  Using cached fiona-1.10.1.tar.gz (444 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  ERROR: Command errored out with exit status 1:
  Complete output (1 lines):
  ERROR: GDAL >= 3.1 is required for fiona. Please upgrade GDAL.

原因分析

检查GDAL版本：

nvidia@pc:~$ gdal-config --version
3.0.4

Ubuntu 20.04 默认仓库中的GDAL版本是 3.0.4，但 fiona >= 1.9.0 要求 GDAL >= 3.1。

解决方案分析

面对版本不兼容，通常有四种解决思路：

方案A：升级GDAL到3.1+（推荐但可能不适用）

# 添加UbuntuGIS PPA（获取新版GDAL）
sudo add-apt-repository ppa:ubuntugis/ppa
sudo apt update
sudo apt install gdal-bin libgdal-dev python3-gdal

# 验证版本
gdal-config --version

⚠️ 注意：UbuntuGIS PPA 主要提供x86_64架构的包，对于aarch64架构（如Jetson），可能不提供预编译包。如果PPA不支持，需要从源码编译GDAL。

方案B：从源码编译GDAL 3.1+（通用但耗时）

# 安装编译依赖
sudo apt install build-essential cmake python3-dev \
  libsqlite3-dev libcurl4-gnutls-dev libtiff-dev \
  libgeos-dev libproj-dev libxml2-dev libexpat-dev

# 下载GDAL源码
cd /tmp
wget https://github.com/OSGeo/gdal/releases/download/v3.9.3/gdal-3.9.3.tar.gz
tar -xzf gdal-3.9.3.tar.gz
cd gdal-3.9.3

# 配置编译选项
./configure --with-python --prefix=/usr/local

# 编译安装（利用多核加速）
make -j$(nproc)
sudo make install
sudo ldconfig

# 设置环境变量
export GDAL_CONFIG=/usr/local/bin/gdal-config
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

方案C：使用旧版Fiona + 旧版OSMnx（快速有效）✅

# 清理缓存
pip cache purge

# 安装支持GDAL 3.0的旧版本
pip install fiona==1.8.22
pip install osmnx==1.6.0

方案D：使用Conda管理依赖（最省心）✅

# 安装Miniconda（aarch64版本）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
bash Miniconda3-latest-Linux-aarch64.sh

# 创建独立环境
conda create -n osmnx python=3.9
conda activate osmnx

# Conda会自动处理所有依赖
conda install -c conda-forge osmnx

我的选择

由于Jetson是aarch64架构，PPA没有提供合适的包，源码编译又比较耗时。我选择了 方案C，使用旧版本成功解决了问题：

# 最终成功的安装命令
pip install fiona==1.8.22
pip install osmnx==1.6.0

# 验证安装
python3 -c "import osmnx as ox; print(f'OSMnx {ox.__version__}')"
# 输出: OSMnx 1.6.0

经验总结

💡 依赖版本矩阵：

环境	OSMnx版本	Fiona版本	GDAL版本
最新环境	1.9.4	1.10.1+	≥ 3.1
兼容环境	1.6.0	1.8.22	≥ 2.0

在aarch64架构上，如果不想折腾编译，降级策略往往是最快的解决方案。

🗺️ 最终稳定环境

经过反复测试，以下环境组合运行稳定：

系统环境

# 操作系统
Ubuntu 20.04 LTS (focal)
# 架构
aarch64 (ARMv8)
# Python
Python 3.8.10

Python包版本

osmnx==1.6.0
fiona==1.8.22
geopandas==0.13.2
networkx==3.1
shapely==2.0.7
pyproj==3.5.0
pandas==2.0.3
numpy==1.24.4
requests==2.32.4

验证脚本

# test_osmnx.py
import osmnx as ox
import fiona
import geopandas as gpd

print(f"OSMnx version: {ox.__version__}")
print(f"Fiona version: {fiona.__version__}")
print(f"Geopandas version: {gpd.__version__}")

# 测试道路数据下载（深圳地区）
print("\nTesting road data download...")
G = ox.graph_from_place('Shenzhen, China', network_type='drive', simplify=True)
print(f"Nodes: {G.number_of_nodes()}, Edges: {G.number_of_edges()}")
print("✅ All tests passed!")

💡 深度分析：为什么会有这么多依赖问题？

1. 地理信息库的"俄罗斯套娃"依赖

OSMnx
  └── geopandas
        ├── fiona (读写地理数据格式)
        │     └── GDAL (底层栅格/矢量库) ← C++库
        ├── shapely (几何操作)
        │     └── GEOS (几何引擎) ← C++库
        ├── pyproj (坐标投影)
        │     └── PROJ (投影库) ← C库
        └── matplotlib (可视化)
  ├── networkx (图论)
  ├── pandas (数据分析)
  └── requests (网络请求)

每个C++库都需要通过pip编译安装，而编译又需要系统头文件和库文件。

2. aarch64架构的特殊性

3. Ubuntu版本的"滞后性"

Ubuntu LTS版本追求稳定，软件包版本往往落后于最新版：

• Ubuntu 20.04 → GDAL 3.0.4 (2020年)

• 最新GDAL → 3.9.x (2024年)

• 差距超过4个大版本

🎯 避坑指南

通用建议

1. 先检查依赖版本：

   apt-cache policy gdal-bin libgdal-dev
   gdal-config --version

2. 优先使用Conda：如果项目允许，Conda的环境管理能力在处理地理信息库时比pip更强大。

3. 锁定版本：在 requirements.txt 中明确版本号，避免自动升级导致不兼容。

4. 使用Docker：对生产环境，考虑使用预装好依赖的Docker镜像：

   docker pull osmnx/osmnx
   docker run -it osmnx/osmnx python3

对于aarch64架构设备

1. 降级策略优先：不要总是追求最新版本，稳定才是第一位

2. 源码编译前确认：确保有足够的时间和磁盘空间（GDAL编译约需30-60分钟，占2GB+空间）

3. 利用系统包：能用 apt install 装的尽量用系统包，pip只装Python级别的库

4. 记录环境：保存完整的环境信息，方便复现

📊 完整安装时间线

[00:00] 开始安装 osmnx (pip install)
[00:01] ❌ 错误：找不到 gdal-config
[00:05] 安装系统GDAL (apt install)
[00:10] ❌ 错误：GDAL版本不兼容
[00:15] 尝试升级GDAL (PPA)
[00:20] ❌ PPA不支持aarch64
[00:25] 尝试源码编译GDAL
[00:55] ✅ GDAL编译完成 (耗时30分钟)
[01:00] ❌ pip安装osmnx仍有其他问题
[01:10] 尝试降级方案
[01:15] ✅ 安装成功！
[01:20] 测试验证通过

总耗时：约1.5小时（大部分时间花在编译GDAL上）

如果直接采用降级方案：

[00:00] pip install fiona==1.8.22
[00:01] ✅ 安装成功
[00:02] pip install osmnx==1.6.0
[00:03] ✅ 安装成功
[00:04] 测试验证通过

总耗时：不到5分钟 🚀

📝 结语

在aarch64架构上安装OSMnx的核心教训是：

1. 理解依赖关系：地理信息库的依赖链很深，需要系统级和Python级双管齐下

2. 版本匹配是关键：不是最新就是最好，兼容性比新特性更重要

3. 降级是武器：当升级困难时，降级到兼容版本往往是捷径

4. 善用Conda：如果环境允许，Conda可以省去大量头疼的依赖问题

希望这篇文章能帮你在OSMnx的安装路上少走弯路！

🔗 参考资料

• OSMnx官方文档

• Fiona GitHub

• GDAL官网

• Conda-forge OSMnx

• NVIDIA Jetson Developer Guide

如果你在安装过程中遇到了其他问题，欢迎留言交流！