QGIS Flatpak 报错 No module named pip 解决方法

通过带有 --devel 的 Flatpak 运行 pip，并使用 --user 安装。这两个标志都有其作用：--devel 会将运行时替换为 SDK，pip 才真正位于其中；--user 会将文件写入沙盒允许写入的目录。

/usr/bin/python3: No module named pip

bwrap: execvp pip3: No such file or directory

ERROR: Could not install packages due to an EnvironmentError:
[Errno 30] Read-only file system: '/usr/lib/python3.11/site-packages/urllib3-1.25.9.dist-info'

error: runtime/org.kde.Sdk/x86_64/5.15-22.08 not installed

这四行都来自同一个沙盒。当您使用 Flathub 的 QGIS 软件包 org.qgis.qgis 时，无论使用哪种 Linux 发行版，只要插件请求一个找不到的 Python 软件包，而您像在其他安装方式上一样尝试使用 pip，就会遇到这些错误。

快速修复

检查是否生效

重启 QGIS，依次打开 插件 > Python 控制台（Plugins > Python Console），输入 import scipy。如果返回一个空提示符，就是想要的结果，因为这意味着 QGIS 能读取安装文件所在的目录，插件也会在那里找到该软件包。ModuleNotFoundError 表示文件落在 QGIS 从不搜索的位置，无论 pip 工作时打印了什么内容。

修复 2：文件落在 QGIS 搜索路径之外

打印 pip 写入的目录：

flatpak run --command=python3 org.qgis.qgis -c "import site; print(site.getusersitepackages())"

将它与 QGIS Python 控制台中的 sys.path 进行比较。如果该目录不在列表中，那么在那里安装的任何内容都不会被导入，不管 pip 报告成功时看起来多么顺利。安装日志从头到尾都很完美，软件包也确实在磁盘上，只是位于 Python 启动时读取的文件夹集合之外。

如果错误没有变化，请转到修复 3。

修复 3：软件包需要编译 C 扩展

安装过程中途会出现编译器错误，而不是 Python 错误。SDK 自带编译器，但并不包含所有开发头文件，而且您无法将沙盒外的头文件交给它。告诉 pip 拒绝源代码构建，改为使用预构建 wheel：

flatpak run --devel --command=pip3 org.qgis.qgis install scipy --user --only-binary=:all:

如果您的平台没有对应的 wheel，请寻找发布 wheel 的软件包。

如果错误没有变化，请转到修复 4。

修复 4：即使使用 --devel，pip3 仍然缺失

SDK 安装没有生效。使用 flatpak list | grep Sdk 确认分支，然后在沙盒内构建 pip，作为备用方案：

flatpak run --command=python3 org.qgis.qgis -m ensurepip --upgrade --user

把它仅仅当作备用方案。这里没有任何来源推荐这种做法，而且没有 --devel 时，它针对的是 Platform 运行时，而不是 SDK。之后回到快速修复的第 3 步。

如果错误没有变化，请转到修复 5。

修复 5：您使用的不是 Flathub 构建

使用 flatpak info org.qgis.qgis 检查。如果没有返回任何内容，说明您的 QGIS 来自其他地方，上面的命令都不适用。QGIS 没有官方 Snap 软件包，因此 Snap 构建来自第三方，并遵循自己的沙盒规则。在 Debian 和 Ubuntu 上，请使用官方 QGIS 软件源，不要使用 Flathub。这样 QGIS 会使用系统 Python，插件依赖可以通过普通 pip 安装。

如果错误没有变化，请发给我，下面的部分说明邮件中应包含哪些内容。

原因

Flatpak 自带独立的 Python，与发行版安装的 Python 隔离，因此您使用系统 pip 或 apt 添加的软件包对 QGIS 不可见。在沙盒内，/usr 以只读方式挂载。普通的 pip install 会尝试写入那里，于是出现包含 python3.11 路径的 [Errno 30] 行，而 --user 会将相同的文件发送到可写目录。

pip 本身位于 SDK 中，不在 QGIS 通常启动的运行时中。没有 --devel 时，根本没有可运行的 pip3，所以报错来自 bwrap，而不是 Python。而且，只有在匹配的 SDK 已经安装到您的机器上时，--devel 才能工作，错误块的最后一行正是在告诉您这一点。

我们的 AI Segmentation 插件会识别 Flatpak QGIS，并引导您使用自动模式。它在我们的服务器上运行，不会在您的机器上安装任何 Python 软件包。

仍未解决？

请发送三项内容：通过 flatpak info org.qgis.qgis 获取的 Flatpak QGIS 版本、您运行的确切命令，以及完整输出，而不只是最后一行。邮箱地址是 stephane.barbot@terra-lab.ai。如果要安装的软件包是我们的 AI Segmentation 插件请求的，请在邮件中说明，因为这会改变我首先检查上面五种修复方法中的哪一种。

常见问题

为什么 pip 在我的终端中可以工作，在 QGIS 中却不行？

您终端里的 pip 属于发行版安装的 Python。Flatpak 有自己的 Python，二者都看不到对方的软件包，因此 apt 和系统 pip 不会改变 QGIS 的现状。每次安装都必须通过 flatpak run，这样才会在沙盒内部执行。

每次安装都需要 --devel 吗？

需要。pip3 位于 SDK 中，而不是 QGIS 启动的运行时中，因此没有 --devel 就没有可运行的内容。每次安装也都要保留 --user，否则您又会写入只读的 /usr，并再次得到 [Errno 30] 行。

软件包实际会落在哪里？

它们会落在沙盒内按用户划分的 site-packages 目录中，修复 2 中的命令会为您打印该目录。将该路径与 QGIS Python 控制台中的 sys.path 进行比较。位于该列表所有文件夹之外的文件，QGIS 永远不会导入。

有没有可以改用的官方 QGIS Snap？

没有。snapcraft.io/qgis 返回 404，Snap 商店中的构建来自第三方。QGIS 文档列出 Flatpak、发行版软件包和 Spack，因此在 Debian 或 Ubuntu 上，Flathub 的替代方案是官方 QGIS 软件源，而不是 Snap。

导入正常后，您就可以回到插件了。我们的两个插件位于 QGIS AI hub。Windows 有自己版本的这个问题，详见 ImportError: DLL load failed while importing _C in QGIS。