Python virtual environment usage¶

Basic usage of Python virtual environments on Quectel Pi. Virtual environments isolate project dependencies and prevent third-party packages from affecting the system Python environment.

Environment Verification¶

First, verify the Python and system environments on the development board:

python3 --version
cat /etc/os-release
command -v pip3 || echo "pip3 not installed"

Item	Description
System	Currently verified on Debian GNU/Linux 13 (trixie)
Python	Currently verified with Python 3.13.5
pip3	pip3 is not detected in the current image by default; install it as needed

Creation and Activation¶

sudo apt update
sudo apt install -y python3-venv python3-pip
mkdir -p ~/projects/python-demo
cd ~/projects/python-demo
python3 -m venv .venv
source .venv/bin/activate

After activation, use the following commands to confirm that the current interpreter and pip come from the virtual environment:

which python
which pip
python --version
pip --version

Dependency Management¶

python -m pip install --upgrade pip
pip install <package_name>
pip freeze > requirements.txt
pip install -r requirements.txt

If the project requires GPIO, serial-port, or networking libraries, install them in the virtual environment. For example:

pip install pyserial requests python-periphery

Deactivate the Environment¶

deactivate

Notes¶

.venv is generally excluded from version control.
requirements.txt should be maintained with the project so that the environment can be reproduced across multiple development boards.
On Debian 13, using --break-system-packages to modify the system Python environment is not recommended by default.