如何在 Raspberry Pi OS 中使用虚拟环境安全安装 Python 库

Raspberry Pi OS 已经预装了 Python3。为了安装额外的 Python 包，最好使用虚拟环境。直接修改系统自带的 Python 可能会导致操作系统出现问题。因此，在安装第三方 Python 库时，务必使用正确的包管理工具。

在 Linux 系统中，你可以通过两种方式安装 Python ：

使用 apt 安装预先配置好的系统包
使用 pip 在虚拟环境中安装 Python 库

这样就能更安全地管理你的 Python 环境，避免影响系统的正常运行。

使用apt安装Python包

通过apt安装的软件包是专门为树莓派操作系统打包的。这些包通常是预编译的，所以安装起来会更快。由于apt会自动管理所有包的依赖关系，因此使用此方法进行安装时，所需的所有子依赖也会一并安装。而且，apt 会确保你卸载包时，不会破坏其他已经安装的包。

例如，如果你想要安装支持Raspberry Pi Build HAT的Python 3库，请运行以下命令：

$ sudo apt install python3-build-hat

要查找通过 apt 分发的 Python 包，可以使用 apt search 命令。大多数情况下，Python 包的名字前面会加上 python- 或 python3- 前缀。例如，你可以通过 python3-numpy 来找到 numpy 包。

使用pip安装Python库

在旧版的 Raspberry Pi OS 中，你可以直接使用 pip 将库安装到系统自带的 Python 中。但从 Raspberry Pi OS Bookworm 版本开始，用户不能再直接将库安装到系统自带的 Python 版本中。

如果你想为所有用户在系统级别安装某个库，可以通过 apt 来安装。

如果尝试在系统范围内安装 Python 包，会出现类似下面的错误信息：

Python 用户长期以来一直面临着操作系统包管理工具（如 apt）与 Python 专用包管理工具（如 pip）之间的冲突。这些冲突不仅包括 Python API 级别的不兼容，还涉及到文件所有权的冲突。

从 Raspberry Pi OS Bookworm 版本开始，通过 pip 安装的包必须安装到 Python 虚拟环境（venv）中。虚拟环境是一个容器，可以让你安全地安装第三方模块，避免它们与系统自带的 Python 发生冲突。

使用虚拟环境中的pip

要使用虚拟环境，你需要创建一个容器来存储该环境。根据你希望如何使用 Python，有几种不同的方式可以创建虚拟环境：

每个项目使用一个独立的虚拟环境

许多用户会为每个 Python 项目创建独立的虚拟环境。通常，这些虚拟环境会放在每个项目的根目录下，文件夹名称一般为 env 或类似的名字。在每个项目的根目录下运行以下命令，可以创建一个虚拟环境配置文件夹：

$ python -m venv env

在开始一个项目之前，从项目的根目录运行以下命令来激活虚拟环境：

$ source env/bin/activate

这时，你应该会看到类似下面的提示符：

(env) $

当你完成项目工作后，可以从任何目录运行以下命令退出虚拟环境：

$ deactivate

每个用户的虚拟环境

你不一定要为每个 Python 项目都创建一个独立的虚拟环境，实际上，你可以为你的整个用户账户创建一个虚拟环境。在运行 Python 代码之前，激活这个虚拟环境。对于那些在多个项目间共享大量库的工作流程来说，这种方式会更方便一些。

如果你打算为多个项目创建虚拟环境，可以考虑把虚拟环境的配置文件放在你的主目录下。为了避免这个文件夹让你的主目录显得杂乱，可以将配置文件夹命名为以点（.）开头的名字，这样默认情况下这个文件夹就会被隐藏起来。

使用如下命令在当前用户主目录的隐藏文件夹中创建虚拟环境：

$ python -m venv ~/.env

在任意目录下运行如下命令开始使用虚拟环境：

$ source ~/.env/bin/activate

然后你应该看到一个类似于下面的提示：

(.env) $

要离开虚拟环境，在任意目录下执行如下命令：

$ deactivate

创建虚拟环境

运行以下命令来创建虚拟环境的配置文件夹，将 <env-name> 替换为你想为虚拟环境使用的名称（例如：env）：

$ python -m venv <env-name>

进入虚拟环境

然后，在虚拟环境的配置文件夹中执行 bin/activate 脚本，进入虚拟环境：

$ source <env-name>/bin/activate

执行后，你应该会看到类似下面的提示符：

(<env-name>) $

其中，(<env-name>) 表示当前终端会话正在使用名为 <env-name> 的虚拟环境。

检查是否在虚拟环境中

你可以使用 pip list 命令查看已安装的包，确认自己是否在虚拟环境中：

(<env-name>) $ pip list

输出会类似于：

 Package    Version 
---------- ------- 
pip        23.0.1 
setuptools 66.1.1

虚拟环境中的已安装包列表通常比系统 Python 中的包要少得多。现在你可以安全地使用 pip 安装包了。所有在虚拟环境中用 pip 安装的包只会安装到该虚拟环境中。在虚拟环境中，python 或 python3 命令会自动使用虚拟环境中的 Python 和已安装的包，而不是系统 Python。

提示：
如果你希望在创建虚拟环境时，预加载系统 Python 中当前安装的所有包，可以在虚拟环境名称前加上 --system-site-packages 参数：

$ python -m venv --system-site-packages <env-name>

退出虚拟环境

当你完成工作并想退出虚拟环境时，运行以下命令:

(<env-name>) $ deactivate

使用Thonny编辑器

我们推荐在树莓派上使用 Thonny 编辑 Python 代码。

默认情况下，Thonny 使用系统自带的 Python。你可以通过点击 Thonny 窗口右下角的解释器菜单，切换到使用 Python 虚拟环境。你可以选择一个已配置的环境，或者通过“配置解释器”来配置一个新的虚拟环境。