This article covers how to get started using Python virtual environments on a headless Raspberry Pi.
If you are using a desktop installation, you can just open up a command line (terminal) window and skip the first few steps.
Step 1. Setup a lite image
For this article I started with a new Raspberry Pi lite image using these instructions:
Step 2. Login to the pi over ssh
Because my pi is called
pi4, I login over ssh like this:
Be sure to adjust the instructions above for the host name that you are using.
Step 3. Determine Python versions
If you are new to Python programming you may not realize that there are two versions available. At the time of this writing, both versions are available when you install a new Raspberry Pi image.
To check each version, run the following at the command line:
I get this for a response:
Don’t worry if you get a different version.
The version I get is:
This can lead to confusion and the wrong version of Python being run.
One way to avoid these issues is to use Python virtual enviroments.
Step 4. Install venv - Python virtual environment module
To quote from the [python doc].
“The venv module provides support for creating lightweight “virtual environments” with their own site directories, optionally isolated from system site directories. Each virtual environment has its own Python binary (which matches the version of the binary that was used to create this environment) and can have its own independent set of installed Python packages in its site directories.”
To install the venv module for Python virtual environments, run this command:
sudo apt-get install python3-venv
You only need to do this once for all future projects.
Step 5. Create a new Python project in a virtual environment
To create a new Python project in a virtual environment, run the following:
cd ~ python3 -m venv hello
This will create a new folder called hello that you should change to:
List the folder contents:
You should see a file called pyvenv.cfg.
Dump the contents of the file to the screen:
You should see a result like this (though your version my vary):
home = /usr/bin include-system-site-packages = false version = 3.7.3
This indicates that version 3 of Python will be used.
The include-system-site-packages = false line indicates that this program will not use any external packages installed elswhere on your system. The idea is to create a program in an isolated environment. That way it can be run on other systems without having to worry about external dependencies.
Step 6. Activate the virtual enviroment
Switch to the hello folder and activate the virtual enviromnent:
cd ~/hello source bin/activate
Your prompt should change to something like this (your user and hostname may be different):
(hello) pi@pi4:~/hello $
Step 7. Create a Python file
Create a new Python file called main.py:
Edit the file using the nano editor:
Paste in this text and save the file:
import sys print('python version:', sys.version[:5])
Step 8. Run the Python file
From within the virtual environment, run this (notice that the command is just
python and not
You should see a reponse like this:
python version: 3.7.3
The version used is specified by the virtual environment as noted previously in the pyvenv.cfg file.
Step 9. Deactivate and run
Now “deactivate” the virtual environent and return to the main operating system command line:
Run the code again using the same command:
You should now get a response like this:
('python version:', '2.7.1')
The version installed with the operating system is used.
Step 10. Verify pip is available
While still deactivated, run this command:
On a fresh install you should get an error that the command is not found. But on an existing system you may see a different response.
Now reactivate the hello environment - note that you don’t need to be in the actual folder to activate an environment:
Now run the command again:
You should see a response like this (your version may vary):
pip 18.1 from /home/pi/hello/lib/python3.7/site-packages/pip (python 3.7)
Remove a Python virtual environment
To remove an environment:
cd ~ rm -rf hello
In this article you learned:
- By default there are currently two versions of Python installed with Raspberry Pi OS
- How to install a Python module to support virtual environmets
- How to create, activate and deactivate Python virtual enviroments
- How to run the same Python code in and out of a virtual environment using different versions
- How to verify and run pip inside a Python virtual environment
- How to remove a Python virtual environment
- venv - Creation of virtual environments - 
About the Author
Mitch Allen works for a robotics company in New England.