ArcGIS Pro Python 教程(ArcPy)

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

ArcGIS Pro 的 Python 教程,核心是学会用 ArcPy 调用地理处理工具,做数据管理、转换、分析与地图自动化。前提是本机已安装 ArcGIS Pro(或 ArcGIS Server 等),ArcPy 不能无许可单独使用。截至 2026 年 11 月,公开文档以 ArcGIS Pro 3.7 为主:默认环境 Python 3.13,可在 Python 窗口、Notebook 或外部脚本里调用同一套工具。下面按「能干什么 → 环境怎么跑 → 脚本怎么写 → 版本注意 → 报错排查」给出可执行路径。

ArcPy 把地理处理工具接到 Python 工作流示意

ArcPy 解决什么问题,和 arcgis 包有何不同

日常批处理、重复制图、批量投影与字段计算,用界面点工具既慢又难复现。ArcPy 是随 ArcGIS 提供的 Python site package,面向本地核心 GIS:数据管理、空间分析、制图自动化,并可访问约两千个地理处理工具。无论在 Pro 内还是外部脚本中运行,调用的都是同一套工具。

不要和 ArcGIS API for Python(包名 arcgis,文档里常写作 ArcGIS API for Python)混为一谈:后者偏 Web GIS(Online / Enterprise),随 Pro 提供,但和面向桌面与本地数据的 ArcPy 分工不同。官方对二者关系有专门说明,核对时可看 Esri:ArcPy 与 ArcGIS API for Python。若你更关心开源栈(如 GeoPandas)和商业桌面各自适合什么场景,可对照本站 GeoPandas 能否替代 ArcGIS、Python 做 GIS 优势在哪,再决定脚本该绑 Pro 许可还是走开源流水线。

  • 优先用 ArcPy:已有 Pro 许可、要直接调 GP 工具箱、工程与图层对象、布局导出。
  • 优先用 arcgis 包:内容项、要素服务、Portal/Online 管理与 Web 图层发布流程。
  • 两者可同机共存:完整默认环境里都有;轻量 arcpy-base 对 Notebook 与 API 支持不完整。

环境怎么准备,脚本从哪里跑

ArcPy 挂在 Pro 自带的 conda 环境 arcgispro-py3 上。自定义环境应克隆该环境,不要直接改默认环境;默认环境损坏时,Pro 部分功能也可能异常,严重时需重装。自 Pro 2.7 起,在版本不冲突的前提下,也可在 Python Command Prompt 里把 ArcPy 装进已有 Python 3 环境;当前文档示例命令为:conda install arcpy=3.7 -c esri。轻量方案可用 conda create -n my-env arcpy-base:依赖更少,能跑几乎全部地理处理与核心 ArcPy(含 NumPy、GDAL、Pandas),但不完整支持 Notebook、ArcGIS API for Python,以及 matplotlib、scipy 等。

安装与补丁从 My Esri 获取(需相应权限);从已退役版本不能直接升级,须先卸载。默认按计算机安装路径一般为 Program Files\ArcGIS\Pro,按用户安装则在用户 Local\Programs\ArcGIS\Pro。更细的 Conda 克隆、包冲突与验收步骤,见本站 ArcGIS Pro 环境怎么配、Conda 命令是什么。

  1. 确认已安装并许可可用的 ArcGIS Pro(系统要求以官网当前页为准)。
  2. 打开「Python 命令提示符」(Python Command Prompt),确认激活的是 arcgispro-py3 或其克隆。
  3. 应用内试跑:分析 → Python 窗口,或使用 ArcGIS Notebooks。
  4. 应用外:用开始菜单的 Python Command Prompt、propy,或直接指向 envs\arcgispro-py3\python.exe;IDE 解释器也指向该 python.exe。
  5. 批处理中调用 propy 时用 call;计划任务可用短路径形式指向 Scripts\propy(按用户安装则把 Program Files 换成 LocalAppData 对应路径)。

验收标准:在选定解释器里执行 import arcpy 无报错,并能列出或运行一个简单 GP 工具(如 CopyFeatures)。若 import 失败,先查是否指错环境、是否未装 Pro,而不是盲目 conda install。

ArcGIS Pro 官方 Python 环境与可用库说明页示意
ArcGIS Pro 官方 Python 环境与可用库说明页示意(截图来源:pro.arcgis.com)

第一个 ArcPy 脚本怎么写

目标:把「手点工具」变成可复现脚本。下面以「指定工作空间 → 跑一个 GP 工具 → 检查结果」为最小闭环;工具名、参数以你本机工具箱为准。

  1. 选定运行入口(Python 窗口适合试参数;正式批处理用 .py + propy/计划任务)。
  2. 导入 arcpy,设置环境:如 workspace、overwriteOutput,必要时设 parallelProcessingFactor。
  3. 用 arcpy.工具名_别名(参数…) 或 arcpy.工具箱别名.工具名 调用;路径尽量用完整路径或明确工作空间相对路径。
  4. 用 Exists、GetCount_management、Describe 做结果校验;失败时读 GetMessages / 异常信息。
  5. 把路径、坐标系、字段名收成变量或配置,再扩展成循环批处理(多要素类、多栅格)。
  6. 从 ArcMap 10.x 迁过来时:语言是 Python 3;制图模块由 arcpy.mapping 改为 arcpy.mp,工程与布局对象模型也不同,不要照搬旧脚本。
  • 工程内自动化:用 arcpy.mp 打开 Aprx、改图层符号、导出布局/地图系列。
  • 数据管理:投影、裁剪、字段计算、游标(da.SearchCursor / UpdateCursor)读写属性。
  • 分析链:把多个 GP 工具串成函数,统一日志与失败重试。

写脚本时优先「小工具可单独跑通 → 再串联」。参数写死在函数外或配置文件里,避免把本机盘符写进多人共用的仓库。

版本、依赖与配置要注意什么

ArcGIS Pro 3.7 于 2026 年 5 月 14 日发布,属 3.x 的次版本,工程文档继续与 3.x 兼容;运行时迁移到 .NET 10。默认 Python 环境(以官方《ArcGIS Pro Python environment》3.7 文档为准)见下表。第三方包升级策略上,Esri 倾向使用仍在安全补丁窗口内的 Python,并严格控制 NumPy 等关键包版本以免 ABI 问题。频道上若出现更高标签的 arcpy 构建,不等于当前正式文档已切换,以你安装的 Pro 版本与官网环境页为准。

组件 ArcGIS Pro 3.7 默认环境(文档所列)
Python 3.13.13
arcpy / arcpy-base 3.7
ArcGIS API for Python(arcgis) 2.4.3
arcgis-mapping 5.0.0
NumPy / pandas / GDAL 2.3.5 / 3.0.0 / 3.12.2
matplotlib / SciPy 3.10.8 / 1.16.3

完整库列表与升级说明见 Esri:ArcGIS Pro 可用 Python 库。历史对照:Pro 3.6 曾将 NumPy 升到 2.x,存在不兼容变更——克隆环境、锁版本、升级后先跑回归脚本,比「直接在默认环境 pip/conda 装最新包」安全得多。

  • 补丁(如 3.7.1)一般要求先装对应主版本,从 My Esri 或应用内更新获取,是否累积以当时公告为准。
  • 不要假设 Anaconda 频道预发布标签等于你正在用的正式版。
  • IDE、计划任务、Notebook 内核必须指向同一解释器,否则会出现「窗口里能跑、脚本里 import 失败」。

常见报错与验收怎么做

脚本挂掉时,先分清是环境问题还是数据/参数问题。环境类:指错 python.exe、默认环境被改坏、克隆环境缺包。数据类:路径含非法字符、图层被锁、坐标系不一致、栅格 NoData 未处理导致计算器失败。栅格与空值相关的典型排查,可参考本站 ArcGIS Pro 栅格计算器报错:去除空值与 arcpy 排查。

  1. 在同一解释器中确认 import arcpy 与 arcpy.GetInstallInfo()(或等价安装信息查询)正常。
  2. 把 GP 工具单独在地理处理窗格跑通,再搬进脚本,排除工具本身许可/扩展模块未启用问题。
  3. 打开 arcpy.env 相关开关与消息级别,打印 GetMessages;对游标与字段名做大小写、别名检查。
  4. 升级 Pro 或换环境后,用一小套「投影 → 裁剪 → 字段计算 → 导出」回归脚本做验收。

验收标准建议:同一输入上,界面工具与脚本结果要素数量、关键字段抽样一致;布局导出分辨率与页面设置符合项目规范;计划任务在无交互桌面会话下仍能写完输出目录。

常见问题

没有 ArcGIS Pro,只装 Python 能不能用 ArcPy?

不能当作无许可独立库使用。即便用 conda 把 arcpy 装进其他环境,仍必须已安装 ArcGIS Pro(或文档允许的其他 ArcGIS 产品)才能真正调用。

该改默认环境还是克隆一份?

应克隆 arcgispro-py3 再装额外包。直接改默认环境风险高,损坏后可能影响 Pro 本身,严重时需要卸载重装。

ArcPy 和 ArcGIS API for Python 可以一起学吗?

可以,但先分清场景:本地 GP 与工程自动化用 ArcPy;Portal/Online 与 Web 内容用 arcgis 包。完整默认环境通常两者都有,轻量 arcpy-base 对后者支持不完整。

从 ArcMap 脚本迁到 Pro 最容易踩什么坑?

Python 2 到 3 的语法与字符串差异,以及 arcpy.mapping 改为 arcpy.mp、工程/布局对象模型变化。旧脚本应逐段改写并做结果对比,而不是只改文件扩展名。

总结:ArcGIS Pro 的 Python 能力,本质是在正确的 conda 环境里稳定调用 ArcPy(必要时再叠加 arcgis 包做 Web GIS)。先保证「克隆环境 + 解释器一致 + 小工具可复现」,再扩展批处理与制图自动化;版本与依赖以当前 Pro 发行说明为准,不要在默认环境里试验性硬升关键包。建议你先按上文最小闭环写出一条可计划任务运行的脚本,环境细节对照本站 Conda 配置文逐步验收;若同时评估开源替代路径,再读 GeoPandas 对比文,按许可与协作方式选型。