Python 虚拟环境使用
2026-04-28
本文档说明 Quectel Pi H1 上 Python 应用开发过程中虚拟环境的基本使用方式，以及项目依赖管理的建议做法。
适用场景
对于需要在 Quectel Pi H1 上进行 Python 脚本开发、应用调试或依赖验证的场景，建议为每个项目建立独立的虚拟环境。
采用虚拟环境的主要目的包括：
- 隔离不同项目之间的依赖版本；
- 避免第三方包影响系统自带 Python 运行环境；
- 便于项目迁移、复现和后续维护；
- 降低开发阶段与部署阶段之间的环境差异。
使用原则
在项目管理中，建议将虚拟环境作为工程目录的一部分统一维护，并配合依赖清单文件使用。对于长期维护的应用，应避免在系统环境中直接安装项目依赖。
推荐做法如下：
- 每个项目单独使用一个虚拟环境；
- 虚拟环境目录与项目目录保持对应关系；
- 依赖版本通过
requirements.txt等文件固化； - 开发、测试和部署尽量基于相同依赖集合执行。
环境准备
首先确认设备中已安装 python3：
python3 --version
如系统尚未安装虚拟环境组件，可执行：
sudo apt update
sudo apt install -y python3-venv
环境创建
建议在项目根目录下创建虚拟环境，常见目录名为 .venv。
python3 -m venv .venv
执行完成后，当前目录中将生成独立的虚拟环境目录，其中包含解释器、pip 及对应包安装路径。
环境启用
在当前 shell 会话中启用该环境：
source .venv/bin/activate
启用后，终端提示符通常会附带环境名称前缀，用于指示当前命令运行在虚拟环境中。
该状态仅对当前会话生效，重新打开终端后需重新执行激活命令。
依赖安装
进入虚拟环境后，可先更新 pip：
pip install --upgrade pip
随后安装所需依赖：
pip install <package_name>
例如：
pip install requests pyserial
上述安装行为仅影响当前虚拟环境，不会修改系统全局 Python 依赖。
依赖固化与恢复
为了便于项目迁移和环境复现，建议在依赖安装完成后导出依赖清单：
pip freeze > requirements.txt
后续在新的同类环境中，可先创建并激活虚拟环境，再执行：
pip install -r requirements.txt
该方式适用于开发板重装系统、迁移项目目录或多设备同步部署等场景。
环境退出
完成操作后，可执行以下命令退出当前虚拟环境：
deactivate
退出后，当前 shell 将恢复使用系统默认 Python 环境。
管理建议
在 Quectel Pi H1 上维护 Python 项目时，建议同时关注以下事项：
.venv目录通常不纳入版本控制；requirements.txt建议随项目一同维护；- 若依赖安装失败，应先检查网络连接、系统时间和构建依赖；
- 对接串口、GPIO、I2C 等硬件接口时，建议先在虚拟环境中完成调试；
- 在部署阶段，如需固定版本，应避免临时升级关键依赖。