在PyQGIS中调用Processing算法
在PyQGIS中调用Processing算法,直接导入 from qgis import processing,然后用 processing.run(算法ID, 参数字典) 执行即可;参数用字典传递,支持图层对象、路径或 memory 输出,也可用 processing.runAndLoadResults 把结果直接加进当前项目。查看参数详情用 processing.algorithmHelp(算法ID),列出全部算法可遍历 QgsApplication.processingRegistry().algorithms()。截至2026年11月,该方式在 QGIS 3.44 LTR 与 4.2 等版本均适用,控制台、独立脚本和 qgis_process 命令行都能用。

在QGIS Python控制台里怎么调用
打开 Plugins → Python Console,这是最省事的上手方式。先导入模块,再按算法要求填参数字典。算法对话框右下角 Advanced 菜单里有 “Copy as Python Command”,可直接复制出准确代码。
- 执行 from qgis import processing。
- 准备输入:当前项目里的图层对象、图层名字符串,或磁盘上的矢量/栅格路径均可。
- 调用 processing.run(“native:buffer”, {“INPUT”: 图层或路径, “DISTANCE”: 100.0, “OUTPUT”: “memory:”})。成功时返回一个字典,键名对应输出(常见为 OUTPUT),值是结果图层或路径。
- 需要立刻看到结果时,改用 processing.runAndLoadResults,它会自动把输出加到 QgsProject。
- 可选参数可省略,走默认值;无效几何等行为受 Processing 全局设置影响。
若工具箱本身打不开或报错,先排查环境,可参考本站 QGIS处理工具箱打不开:Processing错误和工具箱位置 与 QGIS Processing报错:Processing错误和处理工具箱打不开。
独立脚本里如何初始化再调用
脱离 QGIS 界面写批处理或自动化时,必须先正确初始化 QgsApplication 和 Processing 框架,否则会出现 module 没有 run 属性、native 算法找不到等问题。
- 设置前缀路径:QgsApplication.setPrefixPath(“/你的QGIS安装路径”, True)。路径可在控制台里用 QgsApplication.prefixPath() 查到。
- 创建应用:qgs = QgsApplication([], False),然后 qgs.initQgis()。
- 把 python/plugins 目录加入 sys.path,接着 from processing.core.Processing import Processing;Processing.initialize()。
- 注册原生算法:from qgis.analysis import QgsNativeAlgorithms;QgsApplication.processingRegistry().addProvider(QgsNativeAlgorithms())。
- 之后正常 import processing 并调用 run。脚本结束记得 qgs.exitQgis()。
环境变量 PYTHONPATH、库路径(Windows 的 PATH、Linux 的 LD_LIBRARY_PATH)要与目标 QGIS 版本匹配,建议用同一套 OSGeo4W 或官方安装环境。无显示器服务器可设 QT_QPA_PLATFORM=offscreen。更系统的 PyQGIS 接口查找与二次开发路径,见本站 QGIS二次开发怎么学?PyQGIS接口在哪查?。

怎么查算法ID、参数和帮助
算法ID是调用的关键,格式多为 provider:name,例如 native:buffer(qgis:buffer 是别名)。获取方式:
- 在 Processing Toolbox 里把鼠标悬停在算法名称上,状态栏或提示会显示 ID。
- 控制台循环:for alg in QgsApplication.processingRegistry().algorithms(): print(alg.id(), “->”, alg.displayName())。
- 详细参数与输出:processing.algorithmHelp(“native:buffer”),会打印输入输出说明、默认值与类型。
| 常用方法 | 作用 | 典型场景 |
|---|---|---|
| processing.run | 执行并返回结果字典,不自动加载图层 | 脚本批处理、链式调用中间结果 |
| processing.runAndLoadResults | 执行并把输出加到当前项目 | 控制台交互、快速查看效果 |
| processing.algorithmHelp | 打印算法参数与帮助 | 确认 DISTANCE、OUTPUT 等键名 |
| createAlgorithmDialog / execAlgorithmDialog | 弹出与工具箱相同的参数对话框 | 插件里给用户交互填参 |
输出可写文件路径(扩展名决定格式,如 .gpkg)、”memory:” 或 “TEMPORARY_OUTPUT”。官方控制台说明见 QGIS Processing 控制台文档。
输出处理、子算法与注意事项
链式调用多个算法时,务必把同一个 QgsProcessingContext 和 QgsProcessingFeedback 传下去,并设置 is_child_algorithm=True,否则临时图层可能被提前销毁导致后续步骤找不到输入。进度、取消与日志都通过 feedback 报告;出错应 raise QgsProcessingException。
- 默认在后台线程跑;需要 GUI 或主线程操作时注意算法 Flag。
- 矢量默认输出格式、无效几何过滤、线程数等可在 Settings → Options → Processing 里改。
- 命令行无界面时用 qgis_process run native:buffer — INPUT=… DISTANCE=… OUTPUT=…,支持 –json、–verbose;插件算法需先 enable。
- 截至2026年11月,稳定优先选 LTR 3.44.15;跟新功能可用 Latest 4.2.3,但注意 Qt6 下部分插件兼容性。
独立无 GUI 运行细节可核对 QGIS Processing 独立执行器文档。
常见问题
Standalone 里报 processing 没有 run 或找不到 native 算法怎么办?
多数是没调用 Processing.initialize(),或没把 QgsNativeAlgorithms 注册进 processingRegistry。同时检查 setPrefixPath 和 sys.path 是否指向当前安装的 python/plugins,版本必须与绑定的 PyQGIS 一致。
怎么快速得到某算法的准确参数字典?
在工具箱打开该算法对话框,填好参数后点 Advanced → Copy as Python Command,粘贴到控制台即可;或直接跑 algorithmHelp 看键名与类型,再对照改。
临时输出或 memory 图层在下一步算法里找不到?
子算法调用时请传递相同的 context 与 feedback,并设 is_child_algorithm=True,让框架保留临时层所有权;不要依赖默认临时路径在脚本外长期存在。
控制台能跑、独立脚本却失败,常见差在哪?
控制台已由 QGIS 完成初始化;独立脚本必须自己 initQgis、initialize Processing 并处理库路径。无头环境还要设 QT_QPA_PLATFORM=offscreen,否则可能卡在 GUI 相关初始化。
总结:控制台用 from qgis import processing 加 run/runAndLoadResults 最快上手;独立脚本务必完整初始化并注册原生算法,链式调用时统一传 context 与 feedback。建议先在控制台用 Copy as Python Command 验证参数,再搬到脚本;遇到工具箱或框架报错优先对照本站 Processing 排错文章排查环境。