Python3.8安装rasterio报GDAL版本不足、找不到gdal-config错误

报错根因 #

• 初始提示Could not find gdal-config，是因为系统未安装GDAL开发库，或GDAL可执行文件路径未加入系统环境变量
• 后续wheel构建阶段失败的核心原因：当前系统通过gdal-config识别到的GDAL版本为2.4.0，而默认拉取的最新版rasterio要求GDAL版本≥3.1，版本不兼容
• 日志里的pip版本升级提示只是常规警告，不是本次安装失败的诱因

解决方法 #

方案1：安装预编译包（推荐，无需手动处理GDAL依赖） #

源码编译安装需要手动匹配系统GDAL版本，优先使用官方预编译的wheel包可以跳过编译步骤，自带适配的GDAL依赖：

1. 先升级基础安装工具，避免旧版本无法识别预编译包：

pip install --upgrade pip setuptools wheel

2. 清理之前安装失败留下的缓存：

pip cache purge

3. 直接执行安装命令即可，Python3.8环境会自动匹配兼容的rasterio 1.3.x版本，该版本自带GDAL3.x依赖，不会调用系统自带的2.4.0版本GDAL：

pip install rasterio

如果拉取速度慢，可切换至可用的PyPI镜像源执行安装。

方案2：源码编译安装（适用于需要自定义GDAL功能的场景） #

如果必须走源码编译流程，需要先将系统GDAL升级到3.1及以上版本：

• Debian/Ubuntu系统操作步骤：
  1. 卸载系统自带的旧版GDAL：

  sudo apt remove -y gdal-bin libgdal-dev
  

  2. 添加GIS软件源，更新软件列表后安装3.x版本GDAL开发包：

  sudo add-apt-repository ppa:ubuntugis/ppa
  sudo apt update
  sudo apt install -y gdal-bin libgdal-dev
  

  3. 执行gdal-config --version确认输出版本≥3.1后，再执行rasterio安装命令即可。
• CentOS/RHEL系统：先卸载旧版GDAL，配置EPEL及GIS软件源后安装3.x版本的gdal、gdal-devel包，验证版本符合要求后再安装rasterio。
• 若为自行编译安装的GDAL3.x版本，需要将GDAL安装路径下的bin目录加入系统PATH环境变量，保证pip能找到gdal-config命令，同时将lib目录加入LD_LIBRARY_PATH避免运行时找不到动态链接库。

方案3：不升级系统GDAL的降级方案 #

如果受环境限制无法升级系统自带的GDAL2.4.0，可以安装兼容GDAL2.x版本的旧版rasterio，无需修改系统依赖：

pip install rasterio==1.2.10

该版本适配Python3.8环境，支持GDAL2.4.x版本，安装前记得先清理pip缓存避免复用之前的失败构建文件。

排查注意点 #

如果安装过程中再次提示Could not find gdal-config，先执行which gdal-config检查命令是否可被系统识别，如果返回空说明GDAL开发包未正确安装，或是路径未配置到环境变量中，无需反复重装pip排查。

内容的提问来源于stack exchange，提问作者kraivit