Headless Raspberry Pi Python Virtual Environment Setup

mitch

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:

ssh pi@pi4.local

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:

Python 2

python --version

I get this for a response:

Python 2.7.16

Don't worry if you get a different version.

Python 3

python3 --version

The version I get is:

Python 3.7.3

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:

cd ~/hello

List the folder contents:

ls -ls

You should see a file called pyvenv.cfg.

Dump the contents of the file to the screen:

cat pyvenv.cfg

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:

touch main.py

Edit the file using the nano editor:

nano main.py

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 python3):

python main.py

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:

deactivate

Run the code again using the same command:

python main.py

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:

pip --version

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:

source ~/hello/bin/activate

Now run the command again:

pip --version

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)

Troubleshooting

Remove a Python virtual environment

To remove an environment:

cd ~
rm -rf hello

Conclusion

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

Related Articles

References

  • venv - Creation of virtual environments - [1]