How to Install Python Packages in Raspberry Pi OS Bookworm

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.

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.