How to use virtual environments in Thonny

We recently helped an online friend with an application that was completely new to us. We installed said application, Thonny, on our Raspberry Pi and fired it up to try to figure out why it was not honoring the virtualenv directory created by Poetry.

Turns out, Thonny has a built-in system that it uses to manage virtual environments. This diverges a bit from other applications and IDEs that usually honor Pipenv or Poetry virtualenv configurations.

After this discovery, we started exploring the configuration section of Thonny to learn more about how it handles environments so that we could give our friend instructions.

Enable UI expert mode

The first thing we need to do is to enable expert mode. In order to do this, click on Switch to regular mode in the top right corner of the toolbar. Restart Thonny.

Once Thonny starts back up, click on Tools ➔ Options… and on the General tab, click UI Mode and select expert. Don’t worry, you don’t have to be a Python expert to use Thonny in expert mode.

Create a new virtual environment

Click Tools ➔ Options… and then select the Interpreter tab. Click on the dropdown called Which interpreter or device should Thonny use for running your code? and select Alternative Python 3 interpreter or virtual environment. A new dropdown will appear in the window along with the link New virtual environment. Click the link to select a location for your new virtual environment.

We prefer to create the virtual environment directory as a hidden directory at the root of our project. So if your project lives at /home/pi/my-python-project then navigate there and create the directory .venv inside. You should now have new a directory called /home/pi/my-python-project/.venv. Navigate into the newly created directory and click the OK button.

Click the OK button in the Thonny options window to save your changes.

Your interpreter will automatically update in the REPL window.

Confirm this by looking at the initial line in the REPL which should show /home/pi/my-python-project/.venv/bin/python3.

You can now begin installing the packages your project needs. Packages will be installed inside the virtual environment instead of system-wide on your Pi. Why do this? Because you might have projects that depend on different versions of the same package. You may also want to be able to easily wipe the environment and all installed packages when you are done.