PyQGIS安装与开发环境配置
PyQGIS 是 QGIS 自带的 Python 绑定,装好 QGIS 就等于装好了 PyQGIS,不必单独再下一套库。日常写插件可直接用软件内的 Python 控制台;写独立脚本或在 VS Code / PyCharm 里开发,则必须设置前缀路径、PYTHONPATH 与库路径,并在代码里调用 QgsApplication.initQgis()。截至 2026 年 11 月,生产与教程优先选 LTR 3.44.x,需要 Qt6 新特性再选 Latest 4.2.x。装完以「能 import qgis.core 且 initQgis 不报错」作为验收标准。

版本怎么选:LTR 还是 Latest
先想清楚用途,再下安装包。LTR(Long Term Release)经过更长时间的回归测试,至少提供一年左右的缺陷修复,适合生产项目、培训和长期维护的插件。Latest 大约每四个月出一个功能版,每月还有点发布,适合验证新接口,但插件兼容性要自己把关。
| 类型 | 版本(截至 2026 年 11 月) | 适用场景 | 注意点 |
|---|---|---|---|
| LTR | 3.44.15 Solothurn | 生产、教程、稳定插件 | 仍基于 PyQt5;资料与示例最多 |
| Latest | 4.2.3 Belém do Pará | 尝鲜、跟进新 API | 已切到 Qt6 / PyQt6;旧插件需迁移 |
下一档 LTR(原计划约 4.4)因 Qt6 移植回归问题已推迟,预计大约 2027 年 3 月前后再定。版本会持续点发布,下载前建议到QGIS 官方下载页核对当前文件名。同一台机器可用 OSGeo4W 并行安装 LTR 与 Latest,互不覆盖。
各平台怎么安装(内含 PyQGIS)
目标只有一个:系统里出现可用的 QGIS,并且其自带 Python 能加载 qgis 模块。下面按平台给出可执行步骤。
Windows
- 打开官方下载页,在 Standalone 安装器里选 LTR 或 Latest 的 MSI(需要完整投影网格时选带 grids 的更大包)。
- 一路下一步安装;默认路径通常在 C:\Program Files\QGIS … 或 OSGeo4W 根目录。
- 高级用户更推荐 OSGeo4W 网络安装器:Express 勾选 QGIS / QGIS LTR,或 Advanced 在 Desktop 分类下勾选对应包,便于以后增量更新和并行多版本。
- 装完启动 QGIS,菜单 插件 → Python 控制台,输入 from qgis.core import QgsApplication,不报错即说明绑定可用。
macOS
- 下载官方已签名、公证的 DMG(兼容 10.14+,同时覆盖 Intel 与 Apple Silicon)。
- 把 QGIS 拖进 Applications,首次打开若遇安全提示,在系统设置里允许即可。
- 同样用内置 Python 控制台验证 import qgis.core。
Linux(Debian / Ubuntu 等)
- 按 Installation Guide 添加 QGIS 官方仓库(签名密钥 + sources.list)。
- 执行 sudo apt install qgis python3-qgis(需要 GRASS 或服务器组件时再追加对应包)。
- 启动后用控制台确认模块可导入。
跨平台隔离环境可用 conda-forge:conda create -n qgis_dev qgis -c conda-forge(可指定如 qgis=3.44.x),激活后多数路径由环境脚本自动处理,适合专门做开发而不想污染系统 Python 的场景。

独立脚本与 IDE 环境怎么配置
在 QGIS 内部跑控制台或插件时,路径已由软件设好。一旦离开 GUI、用系统或第三方解释器跑脚本,就必须自己初始化运行时,否则会出现找不到模块或找不到动态库的问题。
脚本骨架(逻辑顺序):
- 从 qgis.core 导入所需类。
- 调用 QgsApplication.setPrefixPath(安装前缀, True)。前缀可在已打开的 QGIS Python 控制台里执行 QgsApplication.prefixPath() 查到。
- 创建 QgsApplication([], False)(无界面)或把第二个参数改成 True(需要 GUI)。
- 调用 initQgis(),再写业务代码。
- 结束前调用 exitQgis() 释放资源。
不要把脚本文件命名为 qgis.py,否则会遮蔽真正的绑定包。若还要用 Processing,需在 init 之后把 …/python/plugins 加入 sys.path,再 import processing。
常见环境变量(按实际安装路径改写;不确定时以本机 QGIS 目录为准):
| 变量 | Windows 示例方向 | Linux / macOS 示例方向 |
|---|---|---|
| PYTHONPATH | …\apps\qgis-ltr\python(及 plugins) | …/share/qgis/python 或 macOS 的 Contents/Resources/python |
| PATH / LD_LIBRARY_PATH | 加入 bin 与 apps\qgis-ltr\bin | 加入 lib;macOS 注意框架路径 |
| 其他常配合 | QGIS_PREFIX_PATH、QT_PLUGIN_PATH、GDAL_DATA | 同左,可用启动脚本统一导出 |
Windows 上最稳妥的做法是:用 OSGeo4W 的 o4w_env.bat / py3_env.bat 或复制官方 python-qgis.bat,改成启动你的 IDE,这样解释器、PATH、PYTHONPATH 一次对齐。在 VS Code 里把 Python 解释器指到 QGIS 自带的 python.exe,再用 settings 或 .env 补上 extraPaths。Conda 环境一般已自动处理前缀,仍建议从 QGIS 控制台抄一份 sys.path 做核对。
第三方包(如 requests、geopandas)不要往系统 Python 里乱装。Windows 请开 OSGeo4W Shell,执行 py3_env 后再 python -m pip install …;Conda 用户在对应环境里安装即可。
独立脚本的初始化约定与更多细节,可对照PyQGIS 开发者 Cookbook 入门章节(亦有中文译本,进度较高)。
验收标准与容易踩的坑
- 验收 1: QGIS 内 Python 控制台能 from qgis.core import QgsApplication 且打印出 prefixPath。
- 验收 2: 用配置好的解释器跑最小独立脚本,initQgis / exitQgis 无异常退出。
- 验收 3:(可选)能 import processing 并列出算法,说明插件路径也加对了。
部署给别人用的自定义应用时,通常要求对方先安装同系列 QGIS,或把运行时一并打包(体积会明显变大)。QGIS 4.x 上旧的 PyQt5 插件代码需要迁移到 PyQt6,并在插件 metadata 里写清 qgisMinimumVersion / qgisMaximumVersion,避免仓库误装。
常见问题
报错 ModuleNotFoundError: No module named ‘qgis’ 怎么办?
几乎都是解释器选错或 PYTHONPATH 未指向 QGIS 的 python 目录(以及 plugins)。改用 QGIS 自带 Python,或按上文补齐路径后重开终端 / IDE 再试。
提示找不到 libqgis_core 或某某 DLL 怎么处理?
动态库目录没进搜索路径。Linux 检查 LD_LIBRARY_PATH,Windows 把对应 bin 目录加入 PATH,优先用官方 bat 启动环境,比手改系统变量更不容易漏。
能不能混用系统 Python 和 QGIS 自带的包?
不建议。SIP / PyQt 与 QGIS 编译时绑定的版本必须一致,混用极易出现 ABI 不匹配。第三方库请在 OSGeo4W 的 py3_env 或专用 Conda 环境里安装。
已经装了 Conda 的 qgis,为什么还是 import 失败?
先激活正确环境,再对比 QGIS 控制台里的 sys.path;必要时用 conda develop 把缺失的站点路径补进去。确认装的是 conda-forge 的 qgis 包,而不是空壳依赖。
本章只解决「装上并能在脚本/IDE 里跑起来」:选 LTR 或 Latest → 按平台安装 QGIS → 配好前缀与环境变量 → 用最小脚本验收。建议生产项目固定在 3.44 LTR,开发机若要跟进 4.2,用 OSGeo4W 或 Conda 单独开一套环境,避免两条线互相踩路径。下一章再谈控制台用法与第一段图层代码,这里先把地基夯实。