Virtual environments have been part of python for some time but little used by ordinary users.
Users can no longer install libraries directly into the system version of Python since the advent of python 3.11 (included in Bookworm) although numerous tutorials still have instructions to do this and will fail with an error
error: externally-managed-environment.
You can continue to install into the system (at the risk of overwriting system packages) by passing --break-system-packages to pip.
Install Python packages using apt if possible
Packages installed via apt are packaged specifically for Raspberry Pi OS and apt manages dependencies for all packages and ensures that you don’t break other packages if you uninstall.
To check if the package is available run apt search Package.
Often the names are not immediately obvious and this will show the correct name.
e.g. apt search numpy will show python3-numpy is available.
If the package is not available or you want a newer package you should install into a virtual environment.
Creating virtual environments
You can create a Virtual Environment for each project, or use a single Virtual Environment for all your programs.
To use a virtual environment, create a directory to store the environment.
You can install into ANY directory and ~/.local is a common choice as the container is hidden from normal access; ~/.venv is also often used.
Create a virtual environment by executing the command venv:
python -m venv path_to_virtual_environment
e.g. I use the following to create a directory for the latest python GPIOD library (2.2.2) in ~/.local/gpiod
mkdir ~/.local/gpiod && cd ~/.local && python -m venv --system-site-packages gpiod
It is not necessary to use --system-site-packages but this is a good idea as it gives your program access to all the system libraries whilst in the Virtual Environment.
Install into a virtual environment
To install gpiod into a venv (also named gpiod) with:-
source ~/.local/gpiod/bin/activate
pip install gpiod
deactivate
Using a virtual environment
The normal method is to activate the venv and programs installed into the venv can be run as normal as can other installed code.
<venv> must be replaced by the path to the directory containing the virtual environment.
Run source <venv>/bin/activate
The prompt will change to
(venv) $
When you finish working on a project, run deactivate to leave the virtual environment, but there is no need, especially if you have a single virtual environment for all your programs.
How a Python venv works
When you activate a virtual environment, your PATH variable is changed to include the virtual environment.
You can see this by printing the path with echo $PATH.
You don’t need to activate a virtual environment, you can just specify the full path to that environment’s Python interpreter when invoking Python.
E.g. to use the gpiod environment created above ~/.local/gpiod/bin/python Myprogram.py
You can also use a “shebang” line which points to the environment’s Python interpreter,
i.e. #!<path-to-venv>/bin/python (the <path-to-venv> MUST be a fully qualified path).
This is how scripts installed into the virtual environment work.
Other Resources
Using Python with virtual environments
venv — Creation of virtual environments
