How to prepare a virtual environment to run a gpiozero based project on Raspbian Stretch

When you use a virtual environment to run your application, you isolate the dependencies in its own container.

In such a situation, you can ensure that your application can run alongside other applications with incompatible dependencies.

Therefore, I always favour the use of virtual environment for running my Python applications.

With this in mind, this is a story about preparing a virtual environment to run a gpiozero based project on Raspbian Stretch.

Setting up Raspbian Stretch for Python development

In case you need it, you can follow the guide on how to setup Raspbian Stretch on Raspberry Pi 3 for developing Python 3 applications.

After you had followed through the guide, you can then use python3-venv to create your virtual environment.

Creating a sample project that is based on the GPIO Zero library

Over at the GPIO Zero reference site, we can get a sample script to turn an LED on and off with a push button:

from gpiozero import LED, Button
from signal import pause

led = LED(17)
button = Button(3)

button.when_pressed = led.on
button.when_released =


Let's save the file as in the home directory of the pi user.

Creating a virtual environment for running sample application

After creating your Python script, proceed to create the Python 3 virtual environment.

In order to do so, open up a terminal program and type the following command:

python3 -m venv my-gpiozero-venv

After the command completes, you should find a directory named my-gpiozero-venv in the home directory of your current user. You can find the artefacts to activate the Python 3 virtual environment in that directory.

Next, run the following command to activate the virtual environment in the current terminal program:

source my-gpiozero-venv/bin/activate

When the command completes, your current terminal program will be configured to use your virtual environment for activities related to Python 3. Given that, install the Python dependencies for your GPIO Zero project into your virtual environment:

pip install RPi.GPIO
pip install gpiozero

After you had installed the Python dependencies, you will be able to run your Python script when your virtual environment is activated:


Creating a script to start your Python script with your virtual environment

When you want to make it easy to start your Python script with your virtual environment, you can create a bash script:

source my-gpiozero-venv/bin/activate

Suppose you name your bash script as, run the following command to make it executable:

chmod +x

After you had done so, you can then run your Python script with the following command:


When you terminate your Python script, the deactivate command will deactivate the virtual environment in your terminal program.

About Clivant

Clivant a.k.a Chai Heng enjoys composing software and building systems to serve people. He owns 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.