学习笔记（一）：Windows和Ubuntu系统下的QGIS-python二次开发环境配置方法

0 写在前面

  最近学习在做水文模型二次开发，项目要用到QGIS-python做GIS平台，中间踩了不少坑，目前的教程大多是依赖于QGIS自带的编辑器或者是C++开发环境的配置，基于python的QGIS独立二次开发环境配置方面资料较少或走不通。

  经过相关资料的阅读、各种方法的对比和大佬的指导，在Windows 10系统和Ubuntu 22.04系统中分别尝试开发环境的配置。

  现将Windows 10和Ubuntu 22.04系统下的QGIS-python开发环境配置过程总结归纳下来，以供交流。

1 Win10系统下QGIS-python的开发环境配置

1.1 方法一：使用QGIS软件中的bat文件直接配置环境

  这种方法简单直接，也是资料书籍中推荐的配置方法，主要步骤如下：

step1：QGIS的下载及安装

  在QGIS的官网 (https://www.qgis.org/en/site/forusers/download.html)中提供了两种下载方式，分别是直接下载安装包和使用OSGeo4W进行依赖文件的下载。这里直接下载安装包进行安装，详细过程如下：

  下载安装包，这里给出了一个最新版和一个LTR长期发行版，可以根据自己的需要进行选择：

  下载得到后缀为.msi的安装包，按照步骤选择安装目录进行安装：

step2：QGIS-python的环境配置

  安装完成后打开QGIS程序文件夹，在./QGIS xx.xx/bin/目录下有个python-qgis.bat批处理文件，这个文件临时配置了python调用qgis库所需要的环境。

可以看到里面主要进行了以下几个路径的配置：

‘C:\Program Files\QGIS 3.28.2\apps\qgis\python’;
‘C:\Program Files\QGIS 3.28.2\bin’;
‘C:\Program Files\QGIS 3.28.2\bin\python39.zip’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39\DLLs’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39\lib’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39\lib\site-packages’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39\lib\site-packages\win32’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39\lib\site-packages\win32\lib’;
‘C:\Program Files\QGIS 3.28.2\apps\Python39\lib\site-packages\Pythonwin’;

使用命令行检查qgis库是否可用：
1、打开命令行

WIN+R

2、切换到QGIS的bin目录下

cd C:\\Program Files\\QGIS 3.28.2\\bin

3、在命令行中直接输入python-qgis.bat，进入QGIS下的python配置器

python-qgis.bat

4、导入qgis库并运行，查看是否可用，没有报错，证明qgis库可用

C:\Program Files\QGIS 3.28.2\bin>python-qgis.bat
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from qgis import *
>>> 

可以在PyCharm中直接将python-qgis.bat作为python解释器进行项目开发。至此第一种方法介绍完成。

1.2 方法二：使用conda进行QGIS-python环境的配置

  第一种配置方法虽然高效简单，但是只能借助QGIS自带的python解释器，并且在开发过程中进行其他的一些库的安装并不是很方便，还存在污染QGIS软件自身环境的风险。
  最关键是在做的项目中有个库不用conda装不上（这个问题在ubuntu中并没有遇到），也就有了方法二的探索，即使用conda进行虚拟环境的构建以及QGIS-python环境的配置，详细步骤如下：

step1：Miniconda的下载及安装

  目前用得比较多的有Anaconda和Miniconda，Miniconda仅包含了基础的conda和python依赖包，比较小，所以使用Miniconda。在Miniconda官网（https://docs.conda.io/en/latest/miniconda.html），选择合适的版本进行下载，这里选择Miniconda3 Windows 64-bit版，其中conda的版本是22.11.1 ，python的版本是3.10.8。

根据安装提示逐步进行安装。

  安装完成后打开命令行，输入conda，可能会弹出【‘conda’ 不是内部或外部命令，也不是可运行的程序或批处理文件】提示。

C:\Users\Administrator>conda
'conda' 不是内部或外部命令，也不是可运行的程序或批处理文件。

C:\Users\Administrator>

  这是由于环境变量没有设置的原因。打开Miniconda的文件安装目录，复制condabin的位置：C:\ProgramData\miniconda3\condabin，打开【此电脑】-【属性】-【高级系统设置】-【高级-环境变量】找到系统变量下变量名为PATH的变量，点【编辑】将复制的condabin的位置添加进去。

重新打开命令行再输入conda info，可以看到conda配置完成

C:\Users\Administrator>conda info

     active environment : None
       user config file : C:\Users\Administrator\.condarc
 populated config files : C:\Users\Administrator\.condarc
          conda version : 22.11.1
    conda-build version : not installed
         python version : 3.10.8.final.0
       virtual packages : __archspec=1=x86_64
                          __win=0=0
       base environment : C:\ProgramData\miniconda3  (writable)
      conda av data dir : C:\ProgramData\miniconda3\etc\conda
...

step2：创建虚拟环境

  打开命令行，输入conda create -n pyqgis_env，在conda的默认目录下创建名为pyqgis_env的虚拟环境，在不指定python版本的情况下，python解释器版本和Minconda下载时的对应版本一致。

C:\Users\Administrator>conda create -n pyqgis_env

接着在命令行中输入conda activate pyqgis_env进入pyqgis_env虚拟环境

C:\Users\Administrator>conda activate pyqgis_env

(pyqgis_env) C:\Users\Administrator>

step3：python的QGIS库安装

  这个库的安装过程经历了无数血和泪的探索，中间既试了不同电脑，还建了无数个虚拟机，熟练背诵全网环境配置教程以及官方指南，一度放弃win改用ubuntu。然而就在某个夜晚我进行了第10086+次尝试，竟然成功了！很开心，迸发出无比朴素的分享欲，也就有了这篇学习笔记。

  在虚拟环境下使用conda安装QGIS库，输入conda install -c https://mirrors.ustc.edu.cn/anaconda/cloud/conda-forge/ qgis，这里使用中科大的镜像源进行安装，中间出现了两个提示"failed with initial frozen solve. Retrying with flexible solve."、“failed with repodata from current_repodata.json, will retry with next”，简单尝试了网上的一些方法，没有解决，但接着又配置正常了没有影响安装，所以没有深入了解出现这个问题的原因。

(pyqgis_env) C:\Users\Administrator>conda install -c https://mirrors.ustc.edu.cn/anaconda/cloud/conda-forge/ qgis
Collecting package metadata (current_repodata.json): done
Solving environment: failed with initial frozen solve. Retrying with flexible solve.
Solving environment: failed with repodata from current_repodata.json, will retry with next repodata source.
Collecting package metadata (repodata.json): done
Solving environment: done

安装完成后在虚拟环境命令行中输入python，并import qgis，顺利运行没有报错，证明虚拟环境中的qgis库安装成功了。

(pyqgis_env) C:\Users\Administrator>python
Python 3.11.0 | packaged by conda-forge | (main, Oct 25 2022, 06:12:32) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import qgis
>>>

2 Ubuntu 22.04系统下QGIS-python的开发环境配置

  在ubuntu系统中配置环境的过程就比较丝滑流畅了，没有任何阻碍。主要步骤如下：

step1：创建一个Ubuntu虚拟机

  这里虚拟机系统用的ubuntu最新的22.04版本，虚拟机创建过程不做赘述。

step2：下载Linux版本的QGIS

  在安装目录下打开终端，参照qgis的官网安装方法，依次输入以下命令安装QGIS软件：

sudo apt install gnupg software-properties-common
sudo mkdir -m755 -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/qgis-archive-keyring.gpg https://download.qgis.org/downloads/qgis-archive-keyring.gpg
sudo apt update
sudo apt install qgis qgis-plugin-grass

step3：python下的QGIS库安装

不同于win，ubuntu下的qgis库不需要进行其他环境的配置，在终端中直接输入python3，import qgis，便可以查看qgis库是否安装成功。

3 使用PyCharm打开配置好的QGIS-python开发环境

  为了方便项目的管理，通常使用PyCharm编辑器。这里记录如何使用PyCharm打开配置好的QGIS-python开发环境，开发环境使用win10下方法二配置好的虚拟环境。

打开PyCharm项目，点击【文件】-【设置】

点击【项目】-【python解释器】

点击【⚙】-现有环境-【…】-选择虚拟环境路径下的python解释器

可以看到qgis库是之前安装的3.28.2版本

以上操作完成后创建python脚本，在编辑器中import qgis后运行可能会出现报错：

Traceback (most recent call last):
  File "C:\Users\Administrator\Desktop\pyqgisprj\main.py", line 6, in <module>
    import qgis
ModuleNotFoundError: No module named 'qgis'

这是由于qgis库安装的时候并没有像其他一些常规库安装到虚拟环境的lib文件夹下，而是安装到了另外一个文件夹…/Library/python/中，所以python解释器找不到。

为了解决这个报错，需要把qgis这个包文件复制到项目目录下，

或者在import qgis之前将…/Library/python/地址加入到环境变量中

import sys
sys.path.append(r"C:\ProgramData\miniconda3\envs\pyqgis_env\Library\python")

import qgis

设置完成后，就可以成功导入qgis库了。

4 结语

  以上就是各个系统不同的QGIS-python配置环境的过程，中间可能存在一些遗漏或理解不到位的地方。后续会继续记录学习过程。

学习交流联系方式：776551206@qq.com