1. Installing GPIO Zero

GPIO Zero is installed by default in the Raspberry Pi OS desktop image, Raspberry Pi OS Lite image, and the Raspberry Pi Desktop image for PC/Mac, all available from raspberrypi.com. Follow these guides to installing on other operating systems, including for PCs using the remote GPIO feature.

1.1. Raspberry Pi

GPIO Zero is packaged in the apt repositories of Raspberry Pi OS, Debian and Ubuntu. It is also available on PyPI.

Warning

The version of GPIO Zero in Debian may fall significantly behind the pip and Raspberry Pi OS versions

1.1.1. apt

First, update your repositories list:

pi@raspberrypi:~$ sudo apt update

Then install the package for Python 3:

pi@raspberrypi:~$ sudo apt install python3-gpiozero

or Python 2:

pi@raspberrypi:~$ sudo apt install python-gpiozero

1.1.2. Virtual environment

You may need to install GPIO Zero into a virtual environment. The simplest way is to create a virtual environment with system packages enabled, so that you can access the apt installed libraries without having to install them separately:

pi@raspberrypi:~$ python3 -m venv gpiozero-env --system-site-packages

Then activate the environment (each time you need to use it):

pi@raspberrypi:~$ source ./gpiozero-env/bin/activate

Once activated, the terminal prompt will be preceded by the name of the environment:

(gpiozero-env) pi@raspberrypi:~$

You can then type python to open a Python console or run a Python program, and use apt to install additional libraries from the OS, or pip to install additional libraries from PyPI.

1.1.3. pip

Note

Note that for some time, pip installing gpiozero would not work on the Raspberry Pi 5 due to a bug in the lgpio pin factory. As of July 2026 (the 2.0.1.post1 release), this is now fixed.

If you need to install GPIO Zero into a virtual environment without system packages enabled, first activate your environment (as above) and install GPIO Zero itself with pip:

(gpiozero-env) pi@raspberrypi:~$ pip install gpiozero

You will also need to install a pin library. The default and recommended one is lgpio. This may require compilation, so first install swig and liblgpio-dev:

(gpiozero-env) pi@raspberrypi:~$ sudo apt install swig liblgpio-dev -y

Then install lgpio:

(gpiozero-env) pi@raspberrypi:~$ pip install lgpio

See API - Pins for more information on pin libraries.

1.2. PC/Mac

You may wish to install GPIO Zero on a PC or Mac for either development purposes, using Mock pins or Configuring Remote GPIO. Simply install GPIO Zero with pip, as above. For remote GPIO, you may need the relevant pin library too.

1.3. Documentation

This documentation is also available for offline installation like so:

pi@raspberrypi:~$ sudo apt install python-gpiozero-doc

This will install the HTML version of the documentation under the /usr/share/doc/python-gpiozero-doc/html path. To view the offline documentation you have several options:

You can open the documentation directly by visiting file:///usr/share/doc/python-gpiozero-doc/html/index.html in your browser. However, be aware that using file:// URLs sometimes breaks certain elements. To avoid this, you can view the docs from an http:// style URL by starting a trivial HTTP server with Python, like so:

$ python3 -m http.server -d /usr/share/doc/python-gpiozero-doc/html

Then visit http://localhost:8000/ in your browser.

Alternatively, the package also integrates into Debian’s doc-base system, so you can install one of the doc-base clients (dochelp, dwww, dhelp, doc-central, etc.) and use its interface to locate this document.

If you want to view the documentation offline on a different device, such as an eReader, there are Epub and PDF versions of the documentation available for download from the ReadTheDocs site. Simply click on the “Read the Docs” box at the bottom-left corner of the page (under the table of contents) and select “PDF” or “Epub” from the “Downloads” section.