GPIO Zero

2.0.1 · active · verified Thu Apr 16

GPIO Zero is a Python library that provides a simple and approachable interface to GPIO (General Purpose Input/Output) devices on Raspberry Pi. It abstracts away low-level pin details, offering high-level classes for common components like LEDs, buttons, motors, and sensors, making physical computing accessible. The current version is 2.0.1. It generally follows a release cadence tied to bug fixes and new features, with major versions introducing breaking changes.

Common errors

```
Traceback (most recent call last):
  File "gpiozero.py", line 1, in <module>
    from gpiozero import LED
ImportError: cannot import name 'LED' from 'gpiozero' (/path/to/your/gpiozero.py)
```
cause You have named your Python script 'gpiozero.py', causing Python to try and import your own script instead of the actual gpiozero library.

fix Rename your script file to something different, like `my_project.py` or `led_blink.py`.
```
RuntimeError: Failed to add edge detection. (or similar 'GPIO Busy' error)
```
cause The GPIO pin you are trying to use is currently in use by another program or a previous script did not properly clean up its GPIO usage.

fix Ensure all previous scripts using GPIO have terminated cleanly. You can also explicitly close devices with `device.close()`. If the issue persists, reboot your Raspberry Pi.
```
AttributeError: 'Button' object has no attribute 'pressed'
```
cause You are trying to access a non-existent attribute. Event handlers are typically set via `when_pressed` (a property for assigning a callback), not directly accessed as `pressed`.

fix Use the correct event handler property, for example, `button.when_pressed = my_callback_function` to assign a function to be called when the button is pressed. If you intended to check the state, use `button.is_pressed`.

Warnings

breaking Python 2.x support was removed in GPIO Zero 2.0. The minimum supported Python version is now 3.9.
Fix: Migrate your code to Python 3.9 or newer. Ensure your environment uses Python 3.
breaking The `Robot` class constructor API changed in 2.0. It now expects `Motor` or `PhaseEnableMotor` instances, not tuples of pin numbers.
Fix: Pass initialized `Motor` or `PhaseEnableMotor` objects to the `Robot` constructor. The old tuple-based method is deprecated and will be removed.
breaking The default pin factory changed from `RPiGPIOFactory` to `LGPIOFactory` in version 2.0. This might affect advanced users relying on specific underlying pin library behaviors.
Fix: If your project relies on the previous default, explicitly set `GPIOZERO_PIN_FACTORY=rpigpio` as an environment variable or set it in your code using `gpiozero.Device.pin_factory = 'rpigpio'`.
gotcha Naming your Python script `gpiozero.py` will cause an `ImportError` or unexpected behavior because Python will try to import your script instead of the installed library.
Fix: Rename your script to anything other than `gpiozero.py` (e.g., `my_gpio_project.py`).
gotcha Assigning the *result* of a function call to an event handler (e.g., `button.when_pressed = my_function()`) instead of the function itself (`button.when_pressed = my_function`) will prevent the handler from being called.
Fix: Always assign the function object, not its return value, to event handlers: `button.when_pressed = my_function`.

Install

pip install gpiozero Install via pip
sudo apt update && sudo apt install python3-gpiozero Install on Raspberry Pi OS (Python 3)

Imports

LED
```
from gpiozero import LED
```
Button
```
from gpiozero import Button
```
gpiozero (full import)
```
import gpiozero
```
RPi.GPIO (common mistake)
wrong:
```
import RPi.GPIO
```
correct:
gpiozero is a higher-level abstraction; RPi.GPIO is an underlying library with a different API. Do not mix their usage without understanding pin factories.

Quickstart

This quickstart code demonstrates how to make an LED connected to GPIO pin 17 blink. The `pause()` function keeps the script running indefinitely, allowing the LED to continue blinking.

from gpiozero import LED
from signal import pause

# Replace 17 with your actual GPIO pin number (BCM numbering)
led = LED(17)

led.blink()
pause()

view raw JSON →