ArcPy安装与ArcGIS环境配置

ArcPy
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

ArcPy 无法脱离 ArcGIS 产品单独安装使用:机器上必须先装好 ArcGIS Pro(或 ArcGIS Server),它才会作为默认 Python 发行版 arcgispro-py3 的一部分可用。截至 2026 年 11 月,最新稳定版为 ArcGIS Pro 3.7(配套 ArcPy 3.7、默认 Python 3.13),安装 Pro 后即可 import arcpy。正式开发时不要改默认环境,应克隆一份再装额外包;仅装 conda 包而不装 Pro,仍无法通过许可检查。

ArcPy 依赖 ArcGIS Pro 桌面环境才能正常调用地理处理工具

安装前要满足哪些系统与许可条件

ArcPy 跟着 Pro 走,先把硬件、先决软件和许可核对清楚,能少踩很多坑。Pro 3.7 的官方要求大致如下(以官网最新说明为准)。

项目 最低要求 推荐 / 说明
操作系统 Windows 11(64 位)Home/Pro/Enterprise;Windows Server 2019/2022/2025(需 Desktop Experience) 已不再支持 Windows 10
先决软件 Microsoft .NET Desktop Runtime 10.0.0 或更高 10.x(x64);Edge WebView2 Runtime 132 或更高 .NET 11 不满足要求;per-machine 安装 WebView2 需管理员权限
CPU / 内存 2 核(支持多线程)、8 GB 推荐 4 核以上、32 GB;最优 10 核、64 GB+
存储 / GPU 32 GB 空闲;可用 CPU 渲染 推荐 SSD;独立 GPU 显存 8 GB+;深度学习需 NVIDIA(CUDA compute ≥5.0,驱动 551.61+)
许可 Named User(组织账户)或 Single Use Concurrent Use 已于 2025 年 7 月 1 日弃用

Mac 用户需通过 Parallels 等虚拟机跑 Windows,没有原生 macOS 版。许可一般通过 ArcGIS Online / Enterprise 组织账户或 My Esri 获取;试用期大约 21 天。更完整的软硬件矩阵可对照 ArcPy 官方安装说明。

怎样安装 ArcGIS Pro 并自动获得 ArcPy

ArcPy 本身没有独立安装包,装好 Pro 后默认环境里就已经有了。步骤如下:

  1. 用有下载权限的账号登录 My Esri,或在 ArcGIS Online 组织里进入 My settings → Licenses,下载对应版本的 .exe 安装包(可另下语言包、离线帮助、坐标系数据等可选组件)。
  2. 先装好上面表格里的 .NET Desktop Runtime 10.x 和 WebView2。
  3. 运行安装程序:默认 per-machine 路径为 C:\Program Files\ArcGIS\Pro;也可选 per-user 装到用户 AppData。按向导完成即可。
  4. 安装结束后,开始菜单会出现 “Python Command Prompt”。打开后执行 import arcpy,无报错即说明默认环境可用。

默认环境路径通常类似:C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe。不要直接往这个环境里乱装包,否则可能把 Pro 的地理处理功能弄坏,只能卸载重装恢复。

Esri 官方 ArcPy 安装与环境管理文档页面截图
Esri 官方 ArcPy 安装与环境管理文档页面截图(截图来源:pro.arcgis.com)

如何安全地克隆环境并扩展 ArcPy

日常脚本、第三方库、IDE 调试都建议用克隆环境,既保留 Pro 自带能力,又能自由加包。两种常用做法:

  • 图形界面:在 Pro 里打开 Project → Package Manager → Environment Manager,选中 arcgispro-py3 → Clone,起个新名字(如 my_arcpy),等克隆完成后再激活。
  • 命令行:打开 Python Command Prompt,执行:
    1. conda create –clone arcgispro-py3 –name my_env –pinned(–pinned 保留 pinned 文件,版本更稳)
    2. activate my_env 或用 proswap my_env 切换

从 Pro 2.7 起,也可以把 ArcPy 装进已有的兼容 Python 3 环境(仍须本机已安装对应版本的 Pro):

conda install arcpy=3.7 -c esri

版本号必须和当前 Pro 一致。若只想要轻量环境,可用:

conda create -n my-env arcpy-base

arcpy-base 依赖少,覆盖大部分地理处理工具和核心函数(含 NumPy、GDAL、Pandas 等),但不完整支持 Notebooks、ArcGIS API for Python、matplotlib 等。克隆或 conda 安装需要能访问 conda.anaconda.org 与 repo.anaconda.com;国内网络慢时可配置常用镜像加速。ArcPy 与面向 Web GIS 的 ArcGIS API for Python 是配套关系,后者也会随 Pro 安装,可单独用于 Online/Enterprise。

如何验证安装并在 IDE 里调用

验收标准很简单:在正确激活的环境里能成功导入,并读到许可信息。

  1. 打开 Python Command Prompt(或运行 proenv.bat / propy),确认提示符前缀是你的克隆环境名。
  2. 执行:
    • import arcpy
    • print(arcpy.GetInstallInfo()[‘Version’]) —— 应接近 3.7
    • print(arcpy.ProductInfo()) —— 确认许可已检出
  3. 在 VS Code / Visual Studio 等 IDE 中,把解释器路径指到克隆环境的 python.exe(或默认 arcgispro-py3)。独立脚本务必先激活环境再运行,否则会找不到 arcpy 或许可失败。

常见失败信号:No module named ‘arcpy’(环境没激活或没装 Pro)、许可相关报错(未登录 Named User / 未授权 Single Use)、以及改坏默认环境后 Pro 工具箱灰掉。这时优先检查是否用了克隆环境、防火墙是否拦了 conda 源、许可是否有效。

常见问题

能不能只装 ArcPy、不装 ArcGIS Pro?

不能。即使通过 conda 装了 arcpy 包,运行时仍需本机存在已授权的 ArcGIS Pro 或 ArcGIS Server 来定位许可;没有产品就无法正常使用。

默认环境坏了怎么办?

不要继续往默认环境里修修补补。优先用克隆环境;若默认环境已损坏导致 Pro 异常,通常只能卸载后重装 ArcGIS Pro 恢复。

Pro 3.7 用的是哪个 Python?和旧版差在哪?

Pro 3.7 默认环境使用 Python 3.13.x。更早的 3.4–3.5 多用 3.11,3.0–3.2 多用 3.9。换大版本后第三方包可能要重新安装并做兼容测试。

克隆环境时 conda 很慢或失败怎么处理?

确认能访问官方 conda 源;国内可改用清华等镜像。仍失败时检查磁盘空间、杀毒软件拦截,以及是否用了带 –pinned 的克隆命令。必要时用 Package Manager 图形界面重试。

总结:ArcPy 安装的本质是“先合法安装匹配版本的 ArcGIS Pro,再克隆 arcgispro-py3 做开发环境”。建议立刻做两件事——按系统要求装好 Pro 3.7 并跑通 import arcpy,然后克隆一个专用环境给脚本和 IDE 使用,避免动默认环境。后续章节会单独讲脚本入门与工具调用,本篇只把环境和许可打牢即可。