How to use Python 3 virtual environments to run Python 3 applications on your Raspberry Pi

Whenever I am working on a Python 3 project, I will always use a Python 3 virtual environment for running that project. Therefore, I tend to do the same when it comes to building Python 3 applications to run on a Raspberry Pi.

If you are looking to build Python 3 applications to run on your Pi, then you may find this article useful for you.

Why should we run our Python 3 application in a virtual environment on the Raspberry Pi?

Since a virtual environment helps us isolate Python dependencies within an application runtime, we will be able to run applications with conflicting dependencies on the same Raspberry Pi.

Although we can use Docker to isolate our applications with containers, Python 3 virtual environments are more light-weight for Raspberry Pi.

How to install python3-venv on your Raspbian

If python3-venv is not available on your Raspbian, then you will need to run the following command in a terminal program to install it:

sudo apt-get install python3-venv -y

Running the command to create a Python 3 virtual environment

However, if python3-venv is available on your Raspberry Pi, then you can create a Python 3 virtual environment. For example, if I want to create a virtual environment within the my_venv directory in the home directory of the current user, then I will run the following command:

python3 -m venv ~/my_venv

After the command had completed, a directory named as my_venv will be created in the home directory of the current user.

If you see the following output:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt-get install python3-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Failing command: ['/home/pi/my_venv/bin/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']

then you will need to install python3-venv.

What is inside the ~/my_venv directory?

If you look into the directory that was created by the python3-venv module, you will find everything that is needed to make the terminal session run within an isolated Python 3 environment. Any Python 3 dependencies that are installed for this virtual environment will be contained within this directory.

How to activate the Python 3 virtual environment on your Raspberry Pi

Before you can do anything with that Python 3 virtual environment, you will need to activate it first. In order to activate the Python 3 virtual environment, you need to use the source command to load activate.sh into the current shell session:

source ~/my_venv/bin/activate

After you had done so, you will notice that the shell prompt got appended with the name of your Python 3 virtual environment:

(my_venv) pi@raspberrypi:~ $

This meant that the Python 3 virtual environment had been activated in your current terminal session. If you want to verify that, then you can run the following commands:

which python
which pip

When the commands complete, you should see the following output:

/home/pi/my_venv/bin/python
/home/pi/my_venv/bin/pip

Notice that the two binaries came from the Python 3 virtual environment directory that you had just created.

In addition to that, you can check the Python 3 dependencies that is included within your Python 3 virtual environment:

pip list

When you do so, you may find output similar to the following:

Package       Version
------------- -------
pip           18.1   
pkg-resources 0.0.0  
setuptools    40.8.0

How to install Python 3 dependencies into the virtual environment

Once you had activated your virtual environment, you can then install whatever dependencies that your Python 3 application will need with the pip command. For example, I can run the following command to install Flask into my virtual environment:

pip install flask

After the command complete, you will then be able to run a Python 3 application that uses Flask to realise a web server on your Raspberry Pi. You can verify the pip installation with the following command:

pip list

After the command had completed, you should find new entries in the output:

Package       Version
------------- -------
Click         7.0    
Flask         1.1.1  
itsdangerous  1.1.0  
Jinja2        2.10.1 
MarkupSafe    1.1.1  
pip           18.1   
pkg-resources 0.0.0  
setuptools    40.8.0 
Werkzeug      0.16.0

Running a Python 3 application within your virtual environment

Suppose that you had created a Python 3 script at ~/run_app.py with the following content:

from flask import Flask

app = Flask(__name__)

app.route('/')
def index():
	return 'Welcome to my Flask server running on my Raspberry Pi', 200

app.run('0.0.0.0', 12345)

When you want to run this application, you can use the python command from the virtual environment to do so:

python ~/run_app.py

After you had ran the command, you should see the following output in your shell terminal:

 * Serving Flask app "run_app" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://0.0.0.0:12345/ (Press CTRL+C to quit)

Press CTRL+C to stop the Flask application.

Deactivating the virtual environment

When you want to exit from the virtual environment, you can run the following command:

deactivate

After you had done so, the shell prompt returns back to how it was before you activate the virtual environment:

pi@raspberrypi:~ $

At this point in time, when you run the following commands:

which python
which pip

you may find the following output:

/usr/bin/python

Since I am running this examples from Raspbian lite, the pip is not installed by default. Given these points, you can be sure that your current shell terminal had deactivated the Python 3 virtual environment

Summing up

In summary, you will typically go through the following steps to use Python 3 virtual environments to run your application on your Raspberry Pi:

  • Use python3-venv module to create a directory which contain your Python 3 virtual environment.
  • Use source command to load the activate script within the Python 3 virtual environment directory.
  • Install any Python 3 dependencies that your application with need.
  • Run your Python 3 application while the virtual environment is activated.
  • Exit your virtual environment by using the deactivate script.

About Clivant

Clivant a.k.a Chai Heng enjoys composing software and building systems to serve people. He owns techcoil.com and hopes that whatever he had written and built so far had benefited people. All views expressed belongs to him and are not representative of the company that he works/worked for.