Virtual Environments on a Raspberry Pi | A Beginners Guide

Updated 21 October 2024

In this short and sweet guide, we are going to take a look at how to set up and use a virtual environment (or Venv) on a Raspberry Pi - both in the terminal and in Thonny. 

When using Bookworm OS or later, you may have come across this error when trying to install a Python package:

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.

This is due to changes with Python in Bookworm OS which now requires us to use a virtual environment to install 3rd party packages with PIP. It does add an extra moving part to learn, but thankfully using environments is incredibly easy.

It also offers us an extra layer of protection as a virtual environment is simply a virtual space that we can use for our projects that lowers the risk of breaking or causing conflicts with the rest of the software and Pi operating system.

 


Creating a Virtual Environment

The easiest way to create a virtual environment is through the terminal. Open a new terminal window by selecting it from the taskbar.

The command to create a new virtual environment is:

python3 -m venv --system-site-packages "NAME OF VENV"

With the name of the environment on the end. The name doesn't matter so call it something meaningful, but easy to type. Also, ensure that you do not type the quotation marks. 

As an example, let's look at how we set up the virtual environment in our YOLO computer vision guide. Here we create a virtual environment called "yolo_object" so our line looked like:

python3 -m venv --system-site-packages yolo_object

After entering that command, it should take a few seconds to create that new environment.

We can confirm it has by opening our home folder and seeing the folder for that venv.


Working In a Virtual Environment

Let's start by looking at how to work with virtual environments in the terminal. At any time you can enter a virtual environment by typing in the following source command:

source "NAME OF VENV"/bin/activate

Again you will need to replace "NAME OF VENV" with the name of the environment you created.

Our previous example used "yolo_object", so this line would look like:

source yolo_object/bin/activate

After entering this command you should see the name of the venv to the left of the green text like in the image on the right. This means you are currently working inside of the venv. At this point, you can install the needed libraries and packages needed in your project or do whatever you need to do.

If you ever need to get back into this environment, for example, if you close and reopen the terminal window or restart your Pi, you can simply enter the source command above again and you will reenter it.

Now we must set up Thonny to use this venv. If a library is installed inside of a venv, Thonny won't be able to access it unless it is set up to also work inside of it.

To do so start by opening thonny and ensure that it is in regular mode. It will likely be in simplified mode the first time you open it and will have "Switch to regular mode" in the top right like in the image on the right. 

If it is present, select it and restart Thonny.

Now open the interpreter options menu by selecting Run > Configure Interpreter from the top menu bar. Under the Python executable option, there is a button with 3 dots. 

Select it and navigate to the virtual environment folder we just created. In the file called "bin" select the file called "python3" like shown on the right.

 

Following on from our previous example, the location should be something along the lines of home/pi/yolo_object/bin. Once you have selected the file, click okay.

You should now see the location of that venv under the Python executable option. If you restart your Pi or close and re-open Thonny, it will automatically use this environment.

It will only exit this environment if you manually change it through this drop-down menu. If you ever need to re-enter this environment, simply select it from the drop-down menu.

And now you should be able to enter in your Python code and run your script!

Have a question? Ask the Author of this guide today!

Please enter minimum 20 characters

Your comment will be posted (automatically) on our Support Forum which is publicly accessible. Don't enter private information, such as your phone number.

Expect a quick reply during business hours, many of us check-in over the weekend as well.

Feedback

Please continue if you would like to leave feedback for any of these topics:

  • Website features/issues
  • Content errors/improvements
  • Missing products/categories
  • Product assignments to categories
  • Search results relevance

For all other inquiries (orders status, stock levels, etc), please contact our support team for quick assistance.

Note: click continue and a draft email will be opened to edit. If you don't have an email client on your device, then send a message via the chat icon on the bottom left of our website.

Makers love reviews as much as you do, please follow this link to review the products you have purchased.