Why you need to use a virtual environment in Bookworm when installing Python packages

Bookworm, the latest version of the Raspberry Pi OS, didn’t specifically “introduce” virtual environments, as they are a longstanding Python feature.

However, some updates in Bookworm now require using virtual environments for running pip which means ínstalling Python packages.

There are several Python scripts on this blog, and unless I have already updated the articles, you will need to ensure the installation is made in the virtual environment.

But let’s take a step back.

What are virtual environments

A Python virtual environment is an isolated workspace that allows you to manage project-specific dependencies without affecting the system-wide Python installation.

It is like a sandbox for software. It creates a separate space on your Raspberry Pi where you can install the tools and libraries you need for a specific project. This isolation ensures that any changes you make stay contained within that environment.

Chances are that for a digital picture frame project, the amount of software on your dedicated Raspberry Pi will be rather limited, and you are unlikely to run into a conflict.

However, Bookworm and the latest Python version require you to follow proper development guidelines. And it’s really not complicated.

How it works

If you follow my instructions for installing Pi3D Picture Frame, you have already created a virtual environment called “venv_picframe”.

PictureFrame and packages like Paho (for MQTT) have been installed in this directory.

To install a virtual environment, type

python3 -m venv myenvironment

where “myenvironment” is a name that you choose.

Before installing any software, you need to “activate” the virtual environment so your Raspberry Pi knows to use it. Type:

source myenvironment/bin/activate

You’ll notice your terminal prompt changes to include (myenvironment) at the beginning. This tells you that the virtual environment is now active.

You can now install the libraries your project needs with the environment activated.

For example, to install the Pi3D library for your digital picture frame:

pip install picframe

Any software you install while the environment is active stays within this “sandbox.” It won’t affect your Raspberry Pi’s system or other projects.

When you’re done working, you can “deactivate” the virtual environment by typing

deactivate

So when you are working on PictureFrame, make sure you have activated the Picframe virtual environment with

source venv_picframe/bin/activate

The path is now important

If you call a Python script in a service file, you must also specify the full path to the Python virtual environment you want to use with the script.

So for example, it would look like:

[Unit]
Description=Duplicate Detection and Notification Script
After=network.target

[Service]
ExecStart=/home/pi/venv_picframe/bin/python /home/pi/duplicate_detection.py
WorkingDirectory=/home/pi
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

Conclusion

So whenever you get an error message trying to install a Python package, check if you have activated the virtual environment.

Thank you for your support and motivation.