PyQGIS 是什么？QGIS Python 脚本入门，可免代码
发布于
PyQGIS 是用 Python 代码控制 QGIS 的接口。在 QGIS 中能点击完成的操作，都可以写成几行 Python：加载图层、运行工具、修改样式、导出地图。这样，同一项工作要处理一百个文件时，就不必点击一百次。PyQGIS 随每个 QGIS 一起安装，无需另外添加。
PyQGIS Developer Cookbook 指出，这些 Python 工具与构建 QGIS 本身所用的工具“几乎相同”，所以几乎什么都能做。大多数 QGIS 插件（包括我们的）都是用它编写的。
如今您不必再亲手写代码：聊天机器人可以起草代码，智能体甚至可以完全跳过代码。我们开发了一个智能体，AI Agent。下文会用同样的六项任务测试这两种方式。
PyQGIS 可以在哪里运行
有四个地方，各自适合不同的工作。
| 位置 | 打开方式 | 适用场景 |
|---|---|---|
| Python 控制台 | 插件 > Python 控制台（Ctrl+Alt+P） | 对当前打开的工程做快速修改 |
| 处理脚本 | 工具箱 > 脚本 > 从模板创建新脚本 | 带自有输入参数的可复用工具，和工具箱里的其他工具一样 |
| 插件 | QGIS 配置文件夹中的一个文件夹 | 带自有按钮、可分享给他人的工具 |
| 独立脚本 | 纯 Python，或 qgis_process 命令 | 无需 QGIS 窗口即可运行的任务，例如在服务器上 |
在控制台里可以使用 iface，这个对象用来控制 QGIS 窗口。在 QGIS 之外它并不存在，所以 NameError: name 'iface' is not defined 是 GIS Stack Exchange 上被问得最多的 PyQGIS 问题之一。
处理脚本从 QGIS 为您填好的模板开始。您只需修改输入参数和真正干活的几行代码，脚本就会像内置工具一样出现在工具箱中。
第一个 PyQGIS 脚本
打开 Python 控制台，点击 显示编辑器，在图层面板中选中一个建筑物图层，然后粘贴下面的代码。它会统计每种类型的建筑物数量：
from collections import Counter
layer = iface.activeLayer() # the layer selected in the Layers panel
counts = Counter(f["building"] for f in layer.getFeatures())
for kind, n in counts.most_common(5):
print(kind, n)
print("Total:", layer.featureCount(), "features in", layer.crs().authid())
主要靠三个对象完成工作：QgsProject.instance() 是您的工程，QgsVectorLayer 和 QgsRasterLayer 是工程里的图层，iface 是窗口。API 参考文档列出了所有的类。
用 Python 运行任意 QGIS 工具
处理工具箱中的每个工具，都可以用一行 Python 运行，即 processing.run()，参数与工具窗口里的设置相同：
import processing
result = processing.run("native:buffer", {
"INPUT": "buildings.gpkg",
"DISTANCE": 50,
"OUTPUT": "buffered.gpkg",
})
不必猜测参数名称。先在工具窗口里填好一次设置，再打开底部的 高级 > 复制为 Python 命令（Advanced > Copy as Python Command）。QGIS 会给出可直接粘贴进脚本的完整一行代码。
同样的工具也可以不打开 QGIS，直接在终端里用 qgis_process run native:buffer 运行。需要在服务器上定时执行任务时，就走这条路。
QGIS 4 对 PyQGIS 做了哪些改动
2026 年 3 月 6 日发布的 QGIS 4.0 升级到了更新版本的 Qt，也就是 QGIS 窗口和按钮所用的界面工具包。QGIS 自身的函数几乎没有变化。出问题的是直接调用 Qt 的代码，其中三处改动造成了大部分问题：
| QGIS 3 | QGIS 4 |
|---|---|
简写名称，如 Qt.AlignLeft | 完整名称，如 Qt.AlignmentFlag.AlignLeft |
QRegExp | QRegularExpression |
对话框的 exec_() | exec() |
QGIS 自带脚本 pyqt5_to_pyqt6.py，可以替您改写其中大部分内容，其余的可以用 pyqgis4-checker 查出。只使用 QGIS 工具和 processing.run() 的脚本通常无需修改即可运行。
ChatGPT 或 Claude 能帮您写 PyQGIS 吗？
大多数情况下可以，前提是把您的工程告诉它。我测试了 Claude Sonnet（和 ChatGPT 一样的聊天机器人），它的脚本在六项任务中全部无报错运行。当我描述了图层、字段和文件路径时，六个结果全部正确。当我只给出图层名称时，六个里有一个悄悄出错：脚本照常运行，没有任何异常提示，却在一张高程图的 936 个像素中，把 396 个像素填成了不存在的 0 m 高度。
| 无报错运行 | 结果正确 | |
|---|---|---|
| 聊天机器人，提示中描述了工程 | 6 项中的 6 项 | 6 项中的 6 项 |
| 聊天机器人，只给图层名称 | 6 项中的 6 项 | 6 项中的 5 项 |
| QGIS 内的 AI 智能体，只给一句任务描述 | 6 项中的 6 项 | 6 项中的 6 项 |
道理很简单。聊天机器人看不到您的工程，所以代码质量取决于您描述得有多清楚，而且错误的结果可能和正确的结果看上去完全一样。此外还有一个 QGIS 4 的坑：聊天机器人写的两个打印布局脚本都用了上表中的 Qt 简写名称，在 QGIS 4 中会运行到一半就停止。
我们是怎么测的。 2026 年 9 月 26 日，在 QGIS 3.44.7 中，使用巴厘岛登巴萨市中心的地图数据：六项日常任务，从统计建筑物数量到导出打印布局，每项只尝试一次。只有在运行前就写好的独立检查脚本通过时，结果才算正确。六项任务的样本量很小。
或者免写代码：让智能体替您执行步骤
我们开发了 AI Agent，所以本节讲的是我们自己的插件。它是 QGIS 内的一个对话面板：您输入任务，它读取您的工程、运行工具并检查结果。无需粘贴代码，也无需描述工程。
我给它同样的六句任务描述，没有介绍任何工程情况。它六项全部做对，每项耗时 6.4 到 42.8 秒，六项合计 148.8 秒。它有两次在写入文件前停下来询问，我点击了“允许”。在难倒聊天机器人的那项高程任务上，它先读取图层，再正确设置了空像素。
免费的路线依然很好：控制台、复制为 Python 命令加一个聊天机器人，只要您检查结果，就能走得很远。如果您更愿意直接描述任务并得到图层，智能体可以替您完成这些步骤。
大家常卡在哪里
我们统计了 YouTube 上 QGIS 教程的评论：在 1,692 个有评论的教程中，245 个教程下共有 391 条评论是在求助 Python 或自动化问题。总是这三个问题反复出现：
- 找不到图层。 名称只差一个字母或一个空格，
mapLayersByName("roads")就什么也找不到。 - 距离单位是度。 对
EPSG:4326的图层做 50 m 缓冲区，实际是 50 度的缓冲区，因为这个坐标系以度为单位。请先重投影，详见什么是 CRS。 - 在 QGIS 之外使用
iface。 在窗口之外运行的脚本没有iface，请改用QgsProject和processing.run()。
要点回顾
PyQGIS 是 QGIS 的 Python 接口。它可以在 Python 控制台、处理脚本、插件中运行，也可以用 qgis_process 在 QGIS 之外运行。
processing.run() 可以通过代码运行任何 QGIS 工具，而 复制为 Python 命令 能从工具窗口直接给出准确的一行代码。
QGIS 4 重命名了一些 Qt 名称，例如 Qt.AlignLeft。自己构建窗口的代码可能需要做小的修改。
在我们的六项任务测试中，聊天机器人的代码总能运行，但在没有描述工程时有一次结果是错的。QGIS 内的智能体，例如 AI Agent，只凭一句任务描述就六项全对。
常见问题
PyQGIS 有什么用？
用 Python 自动化 QGIS：加载和编辑图层、对多个文件批量运行工具、设置地图样式、制作打印布局，以及编写可供他人复用的插件或脚本。它也可以在 QGIS 窗口之外运行，用于服务器上的任务。
PyQGIS 就是 Python 吗？
PyQGIS 是一套可以在 Python 中调用的 QGIS 工具。您写的是普通的 Python，PyQGIS 额外提供 QgsVectorLayer 和 processing.run() 之类的内容。它随 QGIS 一起提供，使用的是 QGIS 安装的那个 Python。
如何在 QGIS 中打开 Python 控制台？
插件 > Python 控制台，或按 Ctrl+Alt+P。点击 显示编辑器 可以编写较长的脚本，把它们保存为 .py 文件，并用绿色箭头运行。
我的 PyQGIS 脚本在 QGIS 4 中还能用吗？
只使用 QGIS 工具和 processing.run() 的脚本通常可以。自己构建窗口的脚本往往需要小的改动，例如用 Qt.AlignmentFlag.AlignLeft 代替 Qt.AlignLeft。官方的 pyqt5_to_pyqt6.py 脚本能修复其中大部分问题。
不用 Python 能自动化 QGIS 吗？
可以。图形建模器能以可视化方式串联工具，批处理模式可以对多个文件运行同一个工具。AI 智能体插件则更进一步：您用日常的话输入任务，它在您的工程中运行相应工具。我们的 AI Agent 有免费套餐。
想进一步了解，QGIS 中的 AI 智能体是什么介绍了智能体的工作方式以及如何选择，AI Agent 是我们的插件，可免费试用。什么是 CRS 讲解了大多数脚本都需要先做的重投影，什么是 QGIS MCP 则介绍了适合 Claude Code 和 Cursor 用户的方式。
