Python 虚拟环境使用

在 Quectel Pi H1 系统中通过 pip3 安装 python 库会受系统限制，用户可用虚拟环境与系统环境进行隔离。

当尝试使用 pip3 直接安装包时，可能会遇到以下错误：

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

安装虚拟环境

检查 Python 版本

Quectel Pi H1 板子默认使用 Python 3.13.5，可以通过以下命令查看系统 Python 版本：

python3 --version

安装 venv 模块

安装 Python 虚拟环境模块：

sudo apt update
sudo apt install python3-venv

建立虚拟环境

python3 -m venv .venv

进入虚拟环境

source .venv/bin/activate

进入虚拟环境后，命令行提示符前会显示 (.venv) 标识。

更新 pip

pip3 install --upgrade pip

安装 Python 包

在虚拟环境中，现在可以自由安装所需的 Python 包：

pip3 install <package_name>

退出虚拟环境

deactivate

注意事项

• 虚拟环境是项目隔离的，每个项目可以有自己独立的虚拟环境
• 虚拟环境文件夹（如 .venv）通常不需要提交到版本控制系统中
• 重新打开终端后需要重新激活虚拟环境才能使用其中安装的包