Having issues installing Python packages using the “pip” tool in Raspberry Pi OS Bookworm? There are some extra steps you need to take, involving the creation of a Python virtual environment. Here’s how to do it.
What Has Changed in Raspberry Pi OS Bookworm?
Since the Raspberry Pi 5 is incompatible with earlier versions of Raspberry Pi OS, you will need to install the new “Bookworm” version on it. This is one of thethings to consider when switching to Raspberry Pi 5 from an earlier model.
In previous versions of the Debian-based Raspberry Pi OS operating system (Buster and earlier), it was possible to install Python libraries directly, system-wide, using thepippackage management tool. This is no longer the case in the new Raspberry Pi OS Bookworm, however.
As theRaspberry Pi documentationexplains, the problem was that using a Python-specific tool such aspipcould cause conflicts with theaptOS package manager.
Therefore, from Bookworm onwards, when usingpip, packages must be installed into a sandboxed Python virtual environment, which ensures that they can’t interfere with the system version of Python.
If you try to use the commandpip install [package name]anywhere else in the system, you will receive an error starting with this text:
How to Search for Python Packages With Apt
The first thing to check is whether the Python package you need is available to install using the system-wideaptpackage manager. You can search for packages in the official repository using theapt searchcommand. For instance:
Note the package name, in this case python3-numpy (for Python version 3), and then install it withapt(prefixed withsudofor the required superuser privileges for installation):
If the Python package you need is not available using theaptpackage manager, or you require a newer version of it, you wlll need to use the Python-specificpiptool to install it—within a Python virtual environment.
How to Create a Python Virtual Environment
To install a Python package with the pip tool in Raspberry Pi OS Bookworm, you will first need to create a virtual Python environment usingvenv. We called ours “muo-project”, but you’re able to use any name you want:
It will take a little while to complete, depending on which Raspberry Pi model you’re using. You will then need to change directory to the newly created environment folder, which contains a full Python distribution, and activate it:
The Python virtual environment is now ready to use, and the system prompt will be prepended with its name—in this case,muo-project. This shows that you’re no longer using the system version of Python, but the one inside your virtual environment. So any changes you make to it, or modules you install, won’t affect the system Python.
Note that if you reboot the Raspberry Pi, you will need to reactivate the Python environment to use it again.
If you want to create a Python virtual environment with a copy of all the Python modules currently installed at the operating system level, you can do so by adding the–system-site-packagesflag in the command. E.g :python -m venv –system-site-packages muo-project.
Install Python Packages With Pip
From within the active Python virtual environment, you can now install any packages you need using thepipcommand. For example, to install the Stressberry system stress-testing tool:
It will then install the module, along with any dependencies it requires, within your Python virtual environment. Note that the module will only be available therein and not system-wide.
No More Python Package Conflicts
While the installation of Python packages in Raspberry Pi OS Bookworm using thepiptool requires extra steps, the advantage is that they only then live within the virtual environment and therefore can’t interfere with, or break, the system.
