ArcPy 官方文档
ArcPy 官方文档是 Esri 提供的权威参考,位于 ArcGIS Pro 帮助系统中,中英文版本同步维护。它说明 ArcPy 是一个 Python 站点包,用于执行地理数据分析、数据转换、数据管理和制图自动化,并提供工具、函数、类和模块的完整说明。截至 2026 年 11 月,文档对应最新稳定版 ArcGIS Pro 3.7(内置 ArcPy 3.7 与 Python 3.13.13)。想查语法、模块或示例,直接打开官方中文快速入门页即可。

如何访问和阅读 ArcPy 官方文档
文档入口统一在 pro.arcgis.com,支持语言切换,内容按 ArcGIS Pro 版本更新。动手前先确认自己安装的 Pro 版本,再对照对应章节,避免把 3.x 语法套到旧环境。
- 打开浏览器,进入 ArcPy 中文快速入门文档,先读“什么是 ArcPy”和模块列表。
- 需要英文原文或交叉核对时,同一路径把 /zh-cn/ 换成 /en/ 即可;页面结构一致。
- 查具体工具时,在帮助里搜工具名(例如 Buffer),工具页与 ArcPy 函数页会互相引用。
- 补充资料可看 Esri 维护的 Esri/arcpy GitHub 仓库,里面有 cheatsheet 和按 Pro 版本整理的 Python 发行版包列表。
- 在 ArcGIS Pro 里也可直接按 F1 或从 Python 窗口跳转到上下文帮助,内容与网页版一致。
验收标准:能打开中文快速入门页,并成功找到 arcpy.da、arcpy.mp、arcpy.sa 等模块说明,就算文档入口找对了。
文档里 ArcPy 由哪些部分组成
官方把 ArcPy 拆成工具、函数、类和模块四类,写脚本时必须分清工具与普通函数的差别,否则消息和返回值会对不上。
- 地理处理工具:以函数形式调用(如 arcpy.analysis.Buffer),返回 Result 对象,并产生可通过 GetMessages 读取的消息。
- 非工具函数:不返回 Result,也不生成地理处理消息,文档写在 ArcPy 函数参考里。
- 类:用于创建参数对象、空间参考、字段映射等。
- 模块:按功能划分,常用的有 Charts(arcpy.charts)、Data Access(arcpy.da)、Geocoding(arcpy.geocoding)、Image Analysis(arcpy.ia)、Mapping(arcpy.mp)、Metadata(arcpy.metadata)、Network Analyst(arcpy.nax / arcpy.na)、Sharing(arcpy.sharing)、Spatial Analyst(arcpy.sa)、Utility Network(arcpy.un),以及代表工具箱的 arcpy.analysis、arcpy.management 等。
| 类型 | 是否返回 Result | 是否产生消息 | 文档位置 |
|---|---|---|---|
| 地理处理工具 | 是 | 是 | 工具参考页 + ArcPy 调用说明 |
| 普通函数 | 否 | 否 | ArcPy 函数文档 |
| 类 | 按类方法而定 | 一般否 | ArcPy 类参考 |
| 模块 | — | — | 各模块独立章节 |
写自动化时优先用 arcpy.da 游标做读写,用 arcpy.mp 改布局和图层,用 arcpy.sa / arcpy.ia 做栅格分析,这些在文档里都有独立示例。

按官方文档安装并导入 ArcPy
ArcPy 不是独立下载包,它随 ArcGIS Pro(或 ArcGIS Server)的默认 Python 发行版 arcgispro-py3 一起安装。文档强调:不要直接改默认环境,需要第三方库时先克隆。
- 从 My Esri 或组织门户安装匹配许可的 ArcGIS Pro(当前稳定版以 3.7 为准,3.8 计划于 2026 年 11 月发布)。
- 打开 Python Command Prompt(proenv)或 Pro 内的 Python 窗口 / Notebook,执行 import arcpy,无报错即表示环境可用。
- 需要额外包时,在包管理器或 conda 中克隆 arcgispro-py3,再在克隆环境中安装。
- 若要把 ArcPy 加到已有兼容的 Python 3 环境(Pro 2.7 起支持,且包版本无冲突),可执行:conda install arcpy=3.7 -c esri(版本号与 Pro 对齐)。仍须本机已安装对应 Pro。
- 只要核心工具、体积更小时可用:conda create -n my-env arcpy-base。该环境不包含完整 Notebooks 和 ArcGIS API for Python。
系统要求(ArcGIS Pro 3.7,以官网为准):
| 项目 | 最低 | 推荐 |
|---|---|---|
| 操作系统 | Windows 11 或 Windows Server 2019/2022/2025(64 位,需 Desktop Experience) | 同左,保持厂商支持状态 |
| CPU | 2 核(支持超线程) | 4 核及以上 |
| 内存 | 8 GB | 32 GB |
| 存储 | 32 GB 空闲 | 32 GB+ SSD |
| 其他 | .NET Desktop Runtime 10.0+、Edge WebView2 132+;DirectX 11 / OpenGL 4.3 | 独立 GPU 8 GB+ 显存 |
常见报错:ImportError 多半是没用 Pro 自带解释器或克隆环境坏了;许可相关错误则检查 ArcGIS Pro 是否已登录并授权。验收:在克隆环境里 import arcpy 成功,并能跑通一行 Buffer 或 SearchCursor。
ArcPy 与 ArcGIS API for Python 怎么选
官方文档明确二者互补:ArcPy 面向桌面 GIS,擅长本地数据管理、复杂地理处理工具链和制图自动化;ArcGIS API for Python 面向 Web GIS,侧重门户、要素服务和云端内容。本地 shp/gdb 批处理、mxd/aprx 出图、空间分析工具箱调用,选 ArcPy;操作 ArcGIS Online / Enterprise 内容、发布与管理 Web 图层,选 API。很多工作流会两者一起用:ArcPy 做本地分析,再把结果用 API 推到门户。
常见问题
ArcPy 需要单独下载吗?
不需要。它已包含在 ArcGIS Pro 或 ArcGIS Server 的默认 Python 环境中,安装软件后即可 import。只有在自建 conda 环境时才通过 esri 频道安装对应版本的 arcpy 包。
文档版本和我装的 Pro 对不上怎么办?
以本机 ArcGIS Pro 版本为准(3.7 对应 ArcPy 3.7)。网页默认显示 latest,可在帮助里切换历史版本,或对照 GitHub 上的发行版包列表确认 Python 与第三方库版本。
为什么工具有消息而自己写的函数没有?
只有作为地理处理工具暴露的函数会返回 Result 并写消息;普通 ArcPy 函数不会。需要日志时自己用 print 或 logging,或把脚本封装成工具箱工具。
能不能在非 Windows 或没装 Pro 的机器上跑完整 ArcPy?
桌面完整 ArcPy 依赖 Windows 上的 ArcGIS Pro。部分模块可在带 Advanced runtime 的 ArcGIS Notebooks 中使用,但仍需相应许可;纯 Linux/macOS 本地环境无法替代完整桌面工具链。
总结:ArcPy 官方文档以 pro.arcgis.com 中文快速入门为入口,把工具、模块和安装方式写得很清楚;版本与 ArcGIS Pro 绑定,当前稳定对应 3.7。建议先固定 Pro 版本再克隆环境写脚本,本地批处理优先用 ArcPy,Web 内容再用 API。遇到语法或模块问题,直接回到官方文档对应章节核对即可。