Python Virtual Environment Usage

This document describes the basic use of Python virtual environments on Quectel Pi H1 and provides recommendations for project dependency management.

Scope

For Python script development, application debugging, or dependency verification on Quectel Pi H1, it is recommended to create an independent virtual environment for each project.

The main purposes of using a virtual environment are:

• isolating dependency versions between projects;
• preventing third-party packages from affecting the system Python environment;
• simplifying project migration, reproduction, and maintenance;
• reducing differences between development and deployment environments.

Usage principles

For project management, it is recommended to maintain the virtual environment together with the project directory and to manage dependencies with an explicit dependency file. For long-term maintained applications, avoid installing project-specific packages directly into the system environment.

Recommended practices include:

• using one virtual environment per project;
• keeping the virtual environment directory associated with the project directory;
• freezing dependency versions with files such as requirements.txt;
• using the same dependency set across development, testing, and deployment whenever possible.

Environment setup

First, confirm that python3 is available on the device:

python3 --version

If the virtual environment module is not installed, run:

sudo apt update
sudo apt install -y python3-venv

Environment creation

It is recommended to create the virtual environment in the project root directory. A common directory name is .venv.

python3 -m venv .venv

After execution, an independent environment directory is created in the current path, containing the interpreter, pip, and the package installation location for that environment.

Environment activation

Activate the environment in the current shell session:

source .venv/bin/activate

After activation, the shell prompt usually shows the environment name as a prefix, indicating that commands are running inside the virtual environment.

This state applies only to the current shell session. If a new terminal is opened, the activation command needs to be run again.

Dependency installation

After entering the virtual environment, pip may be updated first:

pip install --upgrade pip

Then install the required packages:

pip install <package_name>

For example:

pip install requests pyserial

These packages are installed only into the current virtual environment and do not modify the system-wide Python dependencies.

Dependency freeze and restore

To support project migration and environment reproduction, it is recommended to export the current dependency list after installation:

pip freeze > requirements.txt

On another device or in a recreated environment, first create and activate a virtual environment, then run:

pip install -r requirements.txt

This workflow is suitable for scenarios such as reflashing the development board, migrating a project directory, or deploying the same application to multiple devices.

Environment deactivation

When the current task is complete, exit the virtual environment with:

deactivate

After deactivation, the shell returns to the system default Python environment.

Management recommendations

When maintaining Python projects on Quectel Pi H1, the following points are recommended:

• the .venv directory is usually excluded from version control;
• requirements.txt should be maintained together with the project;
• if package installation fails, first check network access, system time, and build dependencies;
• for projects involving UART, GPIO, I2C, and other hardware interfaces, complete verification inside the virtual environment before preparing deployment steps;
• for deployment, avoid upgrading critical dependencies temporarily if version consistency is required.