简介这是一个面向Windows 10 Python 3.8环境的Cartopy库免编译安装包专门解决pip安装cartopy时出现的依赖冲突与编译报错问题适合地图制图、气象海洋数据处理等需要地理空间可视化的Python开发者直接使用。压缩包共279个文件约12.44MB主要包含Cartopy核心模块的py源码与pyc编译文件、支持坐标投影的proj动态库、SQLite/GEOS等底层依赖dll以及GSHHS海岸线、河流湖泊等shapefile矢量数据和示例图像、nc温度场与npz高程数据解压后整体复制到Lib/site-packages目录即可完成配置。资源来自科研机构实测可用发布至今已有8833人浏览学习尤其适合因编译环境复杂而安装Cartopy屡次受挫、希望快速搭建地理绘图环境的读者。相比自行下载多个依赖逐一配置这一打包好的版本能省去大量排错时间导入cartopy后即可调用地图投影与海岸线绘制功能。1. 一装cartopy就报错先认清这个库的安装本质用pip装cartopy最常见的结局是一屏红色的ERROR: Failed building wheel for cartopy。难点不在Python代码而在这个库并非纯Python实现绘图背后的投影与几何计算依赖GEOS和PROJ两套C/C库pip找不到预编译wheel时只能现场编译源码。而“更新”场景更折腾升了pip、升了Shapely或刚换Python版本原本能用的环境突然报ModuleNotFoundError和版本不匹配。下面从依赖链讲起给出可复现的安装命令、报错对照与运行验证方法覆盖从新建环境到升级更新的完整链路。2. cartopy安装报错的根源GEOS、PROJ与编译链路2.1 pip安装cartopy时幕后到底在编译什么要理解cartopy的安装报错先明白一个事实pip install cartopy不是“下载压缩包再解压”那么轻量。cartopy主体虽然是Python代码但对外提供投影变换、几何计算能力的核心模块是编译好的C扩展它站在四层依赖之上GEOS几何运算引擎处理相交、缓冲、包含这类空间判断PROJ坐标参考系统库所有地图投影变换都由它完成Shapely封装GEOS的Python库cartopy依赖它与矢量数据进行交换NumPy网格数据与数组接口的基础。当PyPI上有适配当前平台的wheel时pip直接下载二进制包即可。问题在于cartopy的wheel覆盖面有限——新发布的Python版本、较老的操作系统、特殊的架构组合都容易碰不到匹配wheel。此时pip会回退到sdist源码构建要求本机有可用的C/C编译器、GEOS与PROJ的开发头文件以及Python开发头文件。任何一环缺失构建都会在中途报错退出最终汇总成一行Failed building wheel for cartopy。先立住“cartopy不是纯Python库”的认知后续排查才不跑偏。许多新手一见到报错就反复重装cartopy甚至重装Python结果自然是浪费时间。真正的修复方向只有两个手动补齐底部依赖或者换一个会自动处理底部依赖的安装通道。这两条路对应下一章的conda与pip两条路径也对应本节标题里的“编译链路”四个字——报错发生在编译这层就不要在Python代码层找原因。提示判断某个包在目标Python版本下是否存在wheel可以加--only-binary :all:参数安装。pip会直接跳过源码构建路径报错信息远比“编译失败”明确得多。2.2 Shapely 2.0与PROJ版本带来的连锁报错“更新”场景下的多数报错根因是半升级。典型情况是pip install --upgrade cartopy升了新版本但下方依赖仍是旧状态。cartopy对shapely、pyproj只声明最低版本不做API层面的兼容保证于是出现“安装成功、运行报错”的怪象。Shapely 2.0是个明确的分水岭。它把大量几何操作从Python层移进C扩展层对GEOS版本的要求同步提高并且移除了像shapely.speedups这样的旧模块老代码调用shapely.speedups.enable()会直接抛出AttributeError: module shapely has no attribute speedups。在cartopy场景里这类半升级的破坏更隐蔽cartopy本身能import但做缓冲区叠加或矢量裁剪时行为异常报错指向shapely底层几何对象。这类问题的共性在于升级了应用层包却让底层库停留在旧版本。同样地PROJ版本跨度也会制造问题。当前版本的cartopy要求PROJ 8.0以上但不少Linux发行版的系统源里还是PROJ 4.9或6.x。cartopy的构建脚本检测到的是旧版本头文件编译出来的扩展在运行时出现行为异常或明确提示Need at least PROJ 8.0。这类问题不依赖代码调试必须靠统一版本矩阵解决。2.3 先分清楚环境问题、编译问题还是运行期问题报错形态和detectron2、GDAL这类重型扩展库几乎同构按发生阶段可以归成三类处理方式完全不同环境问题Python版本过新导致没有可用wheel、操作系统glibc版本低于manylinux要求、缺少编译工具链。特征是在安装早期报错比如Microsoft Visual C 14.0 or greater is required。编译问题工具链齐全但链接不到GEOS/PROJ。特征是在编译中期出现geos-config not found或Could not find PROJ。运行期问题安装成功但import或首次投影计算时报错。特征是ImportError、undefined symbol、OSError这类动态库加载失败。区分三类问题的现实意义在于环境问题靠换Python版本或换安装通道解决编译问题靠装系统依赖或直接用conda运行期问题靠清理重复依赖副本、统一版本矩阵。下一章的三条安装路径分别对应这三类问题的快捷解法第4章则把每类报错的具体表现和修复命令逐条列出来。3. 用conda-forge和pip把cartopy装进环境的完整命令3.1 conda-forge一条命令装cartopy更新场景同样可靠如果机器上已有Miniconda或Anaconda装cartopy的首选路径是conda而不是pip。conda-forge频道把GEOS、PROJ、Shapely、cartopy的二进制包都预先构建好安装时会自动解析版本兼容性把编译这一步整个省掉# 创建独立环境并固定Python版本避免污染全局解释器 conda create -n geo python3.11 -y conda activate geo # -c 指定频道conda自动解析GEOS/PROJ/Shapely的版本兼容 conda install -c conda-forge cartopy第一条命令创建独立环境并固定Python版本-y跳过中间询问第二条命令激活环境第三条命令装入cartopy-c conda-forge指定依赖来源频道。conda会同时装好匹配的shapely、pyproj、geos和proj不需要手动处理任何编译步骤。更新场景下同样优先走conda而不是pipconda update -c conda-forge cartopy这条命令把cartopy连同依赖的PROJ、Shapely一起更新到彼此兼容的状态而不是像pip那样只处理单个包。对“更新时报错”的多数场景这一步本身就能直接消掉版本错位的隐患。3.2 pip安装时锁住二进制wheel的推荐命令没有conda、只能用pip的环境里正确做法是先升级构建工具再强制只使用预编译wheel# 先升级pip自身避免老版本元数据解析出错 python -m pip install --upgrade pip setuptools wheel # 强制只选择预编译wheel不进入源码编译路径 pip install --only-binary :all: cartopy第一行把pip和构建工具升到新版。第二行的--only-binary :all:是关键参数它限定pip只能选预编译wheel找不到就直接报错而不是擅自进入源码编译。看到报错时可以第一时间判断是“这个Python版本下没有wheel”还是“编译环境有问题”排查半径缩小一大半。如果当前平台有wheel但安装时报依赖冲突可以换用pip install --upgrade cartopy --use-deprecatedlegacy-resolver走旧解析器有时能绕过pip新解析器对间接依赖的过度约束。这个参数在新版pip中随时可能移除只建议临时使用。另外提一个在vscode终端里执行命令时常见的问题先确认终端左下角显示的是项目虚拟环境而不是全局解释器。路径不对会把cartopy装错地方后续import报错的排查方向也会被带偏。3.3 Linux与macOS源码编译前的系统依赖预装当目标平台没有wheel、必须源码编译时需要先手动装齐依赖。Debian/Ubuntu系sudo apt-get install libgeos-dev libproj-dev proj-data pip install cartopylibgeos-dev提供GEOS开发头文件与geos-config脚本libproj-dev提供PROJ库与头文件proj-data是运行期需要的投影数据文件。cartopy的setup脚本正是通过geos-config --cflags定位GEOS位置缺这个脚本是Linux上最常见的编译失败原因。macOS如果用了Homebrew对应命令是brew install proj geos pip install cartopy装完后确认PATH里能找到这两个库必要时执行brew link proj geos强制建立符号链接。装完系统依赖仍报找不到库时多半是头文件路径没被pip的构建环境识别可以加export CPATH/opt/homebrew/include和export LIBRARY_PATH/opt/homebrew/lib把路径显式导出。3.4 conda与pip混用时先卸载再统一的清理步骤最后提醒一个在“更新”场景高发的坑不要同时用两个包管理器管理cartopy的依赖链。典型翻车现场是cartopy由conda安装、shapely由pip安装两者各自带了一份GEOS副本。运行期加载顺序稍有变化就会出现GEOS_ERROR或莫名其妙的undefined symbol。如果环境已经混用先卸载再统一# 先卸载pip一侧的包再移除conda一侧的GEOS副本 pip uninstall shapely cartopy -y conda remove geos -y # 最后用conda统一安装保证所有依赖同源 conda install -c conda-forge cartopy shapely执行顺序不能颠倒否则conda在检查环境时仍会看到旧副本。这一步做完大部分“装的时候好好的用起来报错”的情况都会消失剩下的按第4章的报错对照表逐条处理。4. 高频cartopy安装报错对照与逐条修复4.1 Failed building wheel for cartopy的上方编译日志才有效这是最典型的一条总错误完整输出大概是Building wheel for cartopy (pyproject.toml) ... error ERROR: Failed building wheel for cartopy Failed to build cartopy这个报错本身没有任何可操作信息真正有用的线索在它上方的整段编译日志里。日志几百上千行只需要抓三类关键行它们分别指向不同的缺失环节修复动作完全不同ERROR: Can not find GEOS或geos-config: not found按3.3节装上libgeos-dev再重试或者干脆切到conda。Microsoft Visual C 14.0 or greater is requiredWindows环境缺MSVC工具链。装Visual Studio Build Tools并勾选“使用C的桌面开发”或改用conda通道。unrecognized command line option或大量模板报错编译器版本太老多见于CentOS 7、Ubuntu 16.04这类老系统。升级gcc或者改用官方提供的新版容器镜像。4.2 geos-config与PROJ not found的老版本检测问题Linux上源码编译最常遇到的问题是系统自带PROJ版本太旧报错会明确指向Could not find PROJ. Please install the PROJ library.Ubuntu 18.04自带的PROJ是4.9.3而当前版本的cartopy要求PROJ 8.0以上。此时两个选择一是用conda装新PROJ再装cartopy二是在pip场景下先单独升级pyprojpip install --upgrade pyproj pip install cartopy先装新版pyproj会触发pip提前解析PROJ相关元数据并可能启用pyproj自带捆绑的PROJ库绕开系统老版本检测。若仍然失败说明系统记录的头文件路径覆盖了捆绑版本优先考虑改造环境而不是和编译参数死磕。4.3 undefined symbol说明GEOS副本重复先清理再重装OSError: /usr/local/lib/libgeos_c.so: undefined symbol: GEOSMinimumRotatedRectangleundefined symbol是运行期最难排查的一类安装成功但加载时符号解析失败。根因是环境里存在多个GEOS副本cartopy链接了其中一个运行期加载了另一个两个版本的符号表对不上。修复方向不是重装cartopy而是清理重复的GEOS副本并统一来源具体命令见3.4节。修复完成后不能直接当作收官先用一条命令确认shapely当前实际加载位置排查是否存在外部副本残留python -c import shapely; print(shapely.__file__)正常情况下应该指向conda环境的site-packages或当前虚拟环境目录。如果打印结果带系统路径说明site库存了外部副本检查PYTHONPATH和shell的LD_LIBRARY_PATH是否有残留设置。4.4 No matching distribution found多半是Python版本过新Python 3.12、3.13发布初期cartopy的wheel覆盖往往滞后此时安装报ERROR: Could not find a version that satisfies the requirement cartopy ERROR: No matching distribution found for cartopy先确认自己用的Python版本python --version然后按优先级处理切到Python 3.10或3.11这类wheel覆盖成熟的版本或者改用conda-forge频道它对新Python版本的支持通常早于PyPI最后才是源码编译编译成本高且排错路径长不建议为了一个新版本强行折腾。把本章四类报错整理成对照表方便直接定位报错特征发生阶段首选修复Failed building wheel安装期查看上方编译日志补工具链或切condageos-config not found安装期装libgeos-dev或brew install geosCould not find PROJ安装期换conda或先升级pyprojundefined symbol运行期清理重复GEOS副本统一包管理器No matching distribution安装期降Python版本或换conda-forge5. 装好cartopy后的运行验证与升级更新排雷5.1 用最小脚本验证cartopy的import与投影计算链路安装完成后别急着画地图先跑一个两行的脚本确认依赖链完整# 第一步确认基础模块可加载并打印版本号 import cartopy print(cartopy.__version__) # 第二步确认投影坐标系模块可用 import cartopy.crs as ccrs print(ccrs.PlateCarree())前两步通过后再验证一次实际投影计算import cartopy.crs as ccrs proj ccrs.Mercator() point proj.transform_point(116.4, 39.9, ccrs.PlateCarree()) print(point)把一个经纬度点投影到Mercator平面坐标输出有限数值而不是NaN说明GEOS/PROJ扩展加载成功。首次实例化投影对象时cartopy会加载proj数据库文件这一步偏慢是正常的不属于报错。5.2 升级更新时锁定版本矩阵而不是单包升级升级cartopy时坚持一个原则不单独升级cartopy。新版本往往对shapely、pyproj、numpy有最低版本要求一次只动一个包极易制造不匹配。锁定版本安装pip install cartopy0.24.1 shapely2.0 pyproj3.5 numpy2.0如果当前环境已经被反复折腾得不干净最可靠的方式是导出再重建环境而不是原位升级。conda用户执行conda env export -n geo environment.yml conda env remove -n geo conda env create -f environment.yml导出文件会把当前环境完整的版本矩阵固化下来重建后如果新包导致问题直接回滚到旧配置即可。5.3 离线环境更新cartopy的预下载与本地安装在无法直接访问外网的生产环境更新cartopy常见做法是先在能联网的机器上用pip下载完整依赖集再拷贝进去离线安装# 在联网机器上把cartopy及其全部依赖的wheel收进本地目录 pip download cartopy -d ./cartopy_wheels # 在离线机器上绕过网络索引只从本地目录安装 pip install --no-index --find-links ./cartopy_wheels cartopy两条命令的pip版本和Python版本必须一致否则wheel的标签格式可能不被识别。离线安装最大的坑是传输目录时丢了文件报ERROR: Cannot unpack file时先验证wheel目录的完整性而不是反复重试安装命令。conda的离线安装相对更麻烦conda install --offline只能从本地包缓存读取缓存里没有就装不上所以内网机器通常优先走pip方案。装完再跑一遍5.1节的验证脚本确认版本号与依赖矩阵符合预期整个升级更新流程才算真正结束。本文还有配套的精品资源点击获取