# Python虚拟环境使用

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文档说明Quectel Pi H1上Python应用开发过程中虚拟环境的基本使用方式，以及项目依赖管理的建议做法。

# 适用场景

对于需要在Quectel Pi H1上进行Python脚本开发、应用调试或依赖验证的场景，建议为每个项目建立独立的虚拟环境。

采用虚拟环境的主要目的包括：

- 隔离不同项目之间的依赖版本；

- 避免第三方包影响系统自带Python运行环境；

- 便于项目迁移、复现和后续维护；

- 降低开发阶段与部署阶段之间的环境差异。

# 使用原则

在项目管理中，建议将虚拟环境作为工程目录的一部分统一维护，并配合依赖清单文件使用。对于长期维护的应用，应避免在系统环境中直接安装项目依赖。

推荐做法如下：

- 每个项目单独使用一个虚拟环境；

- 虚拟环境目录与项目目录保持对应关系；

- 依赖版本通过 *requirements.txt* 等文件固化；

- 开发、测试和部署尽量基于相同依赖集合执行。

# 环境准备

首先确认设备中已安装 *python3*：

```bash
python3 --version
```

如系统尚未安装虚拟环境组件，可执行：

```bash
sudo apt update
sudo apt install -y python3-venv
```

# 环境创建

建议在项目根目录下创建虚拟环境，常见目录名为 *.venv*。

```bash
python3 -m venv .venv
```

执行完成后，当前目录中将生成独立的虚拟环境目录，其中包含解释器、*pip* 及对应包安装路径。

# 环境启用

在当前shell会话中启用该环境：

```bash
source .venv/bin/activate
```

启用后，终端提示符通常会附带环境名称前缀，用于指示当前命令运行在虚拟环境中。

该状态仅对当前会话生效，重新打开终端后需重新执行激活命令。

# 依赖安装

进入虚拟环境后，可先更新 *pip*：

```bash
pip install --upgrade pip
```

随后安装所需依赖：

```bash
pip install <package_name>
```

例如：

```bash
pip install requests pyserial
```

上述安装行为仅影响当前虚拟环境，不会修改系统全局Python依赖。

# 依赖固化与恢复

为了便于项目迁移和环境复现，建议在依赖安装完成后导出依赖清单：

```bash
pip freeze > requirements.txt
```

后续在新的同类环境中，可先创建并激活虚拟环境，再执行：

```bash
pip install -r requirements.txt
```

该方式适用于开发板重装系统、迁移项目目录或多设备同步部署等场景。

# 环境退出

完成操作后，可执行以下命令退出当前虚拟环境：

```bash
deactivate
```

退出后，当前shell将恢复使用系统默认Python环境。

# 管理建议

在Quectel Pi H1上维护Python项目时，建议同时关注以下事项：

- *.venv* 目录通常不纳入版本控制；

- *requirements.txt* 建议随项目一同维护；

- 若依赖安装失败，应先检查网络连接、系统时间和构建依赖；

- 对接串口、GPIO、I2C等硬件接口时，建议先在虚拟环境中完成调试；

- 在部署阶段，如需固定版本，应避免临时升级关键依赖。