Python Virtual Environment Usage

Installing Python libraries through pip3 in the Quectel Pi H1 system is subject to system restrictions. Users can use a virtual environment to isolate their setup from the system environment.

When you try to install packages directly using pip3, you may encounter the following error:

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.

Install the Virtual Environment

Check the Python Version

The Quectel Pi H1 uses Python 3.13.5 by default. You can check the system Python version with the following command:

python3 --version

Install the venv Module

Install the Python virtual environment module:

sudo apt update
sudo apt install python3-venv

Create a Virtual Environment

python3 -m venv .venv

Activate the Virtual Environment

source .venv/bin/activate

After activating the virtual environment, the (.venv) identifier will be displayed before the command line prompt.

Upgrade pip

pip3 install --upgrade pip

Install Python Packages

In the virtual environment, you can now freely install the required Python packages:

pip3 install <package_name>

Deactivate the Virtual Environment

deactivate

Notes

• Virtual environments are project-isolated, each project can have its own independent virtual environment
• Virtual environment folders (such as .venv) usually do not need to be committed to version control systems
• After reopening the terminal, you need to reactivate the virtual environment to use the packages installed in it