PyQGIS安装与开发环境配置

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

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 不报错」作为验收标准。

QGIS 官方下载页,可选 LTR 与 Latest 安装包
QGIS 官方下载页,可选 LTR 与 Latest 安装包(截图来源:www.qgis.org)

版本怎么选: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

  1. 打开官方下载页,在 Standalone 安装器里选 LTR 或 Latest 的 MSI(需要完整投影网格时选带 grids 的更大包)。
  2. 一路下一步安装;默认路径通常在 C:\Program Files\QGIS … 或 OSGeo4W 根目录。
  3. 高级用户更推荐 OSGeo4W 网络安装器:Express 勾选 QGIS / QGIS LTR,或 Advanced 在 Desktop 分类下勾选对应包,便于以后增量更新和并行多版本。
  4. 装完启动 QGIS,菜单 插件 → Python 控制台,输入 from qgis.core import QgsApplication,不报错即说明绑定可用。

macOS

  1. 下载官方已签名、公证的 DMG(兼容 10.14+,同时覆盖 Intel 与 Apple Silicon)。
  2. 把 QGIS 拖进 Applications,首次打开若遇安全提示,在系统设置里允许即可。
  3. 同样用内置 Python 控制台验证 import qgis.core。

Linux(Debian / Ubuntu 等)

  1. 按 Installation Guide 添加 QGIS 官方仓库(签名密钥 + sources.list)。
  2. 执行 sudo apt install qgis python3-qgis(需要 GRASS 或服务器组件时再追加对应包)。
  3. 启动后用控制台确认模块可导入。

跨平台隔离环境可用 conda-forge:conda create -n qgis_dev qgis -c conda-forge(可指定如 qgis=3.44.x),激活后多数路径由环境脚本自动处理,适合专门做开发而不想污染系统 Python 的场景。

配置好后的 PyQGIS 脚本与地图联动示意

独立脚本与 IDE 环境怎么配置

在 QGIS 内部跑控制台或插件时,路径已由软件设好。一旦离开 GUI、用系统或第三方解释器跑脚本,就必须自己初始化运行时,否则会出现找不到模块或找不到动态库的问题。

脚本骨架(逻辑顺序):

  1. 从 qgis.core 导入所需类。
  2. 调用 QgsApplication.setPrefixPath(安装前缀, True)。前缀可在已打开的 QGIS Python 控制台里执行 QgsApplication.prefixPath() 查到。
  3. 创建 QgsApplication([], False)(无界面)或把第二个参数改成 True(需要 GUI)。
  4. 调用 initQgis(),再写业务代码。
  5. 结束前调用 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 单独开一套环境,避免两条线互相踩路径。下一章再谈控制台用法与第一段图层代码,这里先把地基夯实。