Key Takeaways
- Raspberry Pi OS Bookworm requires the installation of Python packages in a virtual environment to prevent conflicts with the system version of Python.
- You can use the apt package manager to search for and install Python packages, but if the package is not available or you need a newer version, you’ll need to use the pip tool within a virtual environment.
- Any changes or installations made within the virtual environment won’t affect the system version of Python.
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 the things 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 the pip package management tool. This is no longer the case in the new Raspberry Pi OS Bookworm, however.
As the Raspberry Pi documentation explains, the problem was that using a Python-specific tool such as pip could cause conflicts with the apt OS package manager.
Therefore, from Bookworm onwards, when using pip, 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 command pip install [package name] anywhere else in the system, you will receive an error starting with this text:
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.
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-wide apt package manager. You can search for packages in the official repository using the apt search command. For instance:
apt search numpy
Note the package name, in this case python3-numpy (for Python version 3), and then install it with apt (prefixed with sudo for the required superuser privileges for installation):
sudo apt install python3-numpy
If the Python package you need is not available using the apt package manager, or you require a newer version of it, you wlll need to use the Python-specific pip tool 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 using venv. We called ours “muo-project”, but you can use any name you want:
python -m venv muo-project
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:
cd muo
source bin/activate
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-packages flag 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 the pip command. For example, to install the Stressberry system stress-testing tool:
pip install stressberry
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 the pip tool 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.
