Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
GPIO Zero lets you control Raspberry Pi pins through straightforward Python objects. In this tutorial, you’ll wire a resistor-protected LED, blink it, read a push button, connect the button to the LED, and adjust brightness with PWM. The examples use Python 3 and BCM pin numbering; they also note the pin-backend issue to check on Raspberry Pi 5.
What GPIO Zero does
GPIO Zero is a Python library for physical-computing projects. Instead of configuring pin modes and handling low-level input and output yourself, you can create objects such as LED and Button, then call methods or connect their behavior. The library also includes interfaces for devices such as buzzers, motion sensors, motors and servos. Those software interfaces do not replace the drivers or power supplies that some components require.
GPIO Zero is a useful starting point for ordinary beginner projects, not a universal solution for every device. Its high-level API makes simple code easier to read, while the selected pin factory—the library that communicates with the hardware—still matters for compatibility. The stable documentation identifies GPIO Zero version 2.0.1; check the current stable documentation when working with a different release or operating system.
Safety and parts
Raspberry Pi GPIO uses 3.3 V logic. A GPIO pin is for a logic signal, not for powering a motor, relay, LED strip, speaker or servo directly. Never apply 5 V to a GPIO input. Switch the Pi off before changing the wiring, and check component polarity and labels before restoring power.
#1 Best Overall
- 5 sets of code: Python (compatible with 2&3), C, Java, Scratch and Processing (Scratch and Processing code provide graphical interfaces)
- Detailed tutorial: Can be downloaded (in English, 962-page in total) or viewed online (original in English, can be translated into other languages by browsers) (The tutorial link can be found on the product box, no paper tutorial)
- 128 projects from simple to complex: Provides step-by-step guide with electronics and components knowledge, each project has schematics, wiring diagrams, complete code and detailed explanations
- 223 items in total: This ultimate kit includes the most commonly used electronic components, modules, sensors, wires and other compatible items
- Compatible models: Raspberry Pi 5 / 500 / 400 / 4B / 3B+ / 3B / 3A+ / 2B / 1B+ / 1A+ / Zero 2 W / Zero W / Zero (NOT included in this kit)
- Use a current-limiting resistor with a bare LED. A 220 Ω or 330 Ω resistor is a suitable beginner choice for the example circuit.
- Use a suitable transistor, MOSFET, motor driver, relay module or other driver for loads that need more current than a GPIO signal can provide. Higher-current devices may also need a separate supply; where the circuit requires a shared reference, connect its ground to Pi ground.
- Use an appropriate analogue-to-digital converter (ADC) to measure an analogue sensor. A GPIO input is not a general-purpose analogue voltage meter.
You need a Raspberry Pi with a 40-pin GPIO header, Raspberry Pi OS, a power supply, a microSD card, a breadboard, an LED, a resistor and jumper wires. Add a momentary push button for the button exercises. A Pi Zero 2 W has a 40-pin header footprint but ships without the header populated, so it needs header pins or a suitable GPIO accessory for ordinary jumper-wire use; see the Pi Zero 2 W product information. A Pi 4 or another Pi with an accessible 40-pin header also works for these basic exercises; a Pi 5 is not required.
Understand BCM and physical pin numbers
Each GPIO connection has a BCM number, which identifies the signal, and a physical pin number, which identifies its position on the board’s header. GPIO Zero uses BCM numbering by default. Thus LED(17) refers to GPIO17, which is physical pin 11—not physical pin 17. Physical pin 6, for example, is a ground pin.
Use these connections throughout the tutorial:
- LED: GPIO17 (physical pin 11) → resistor → LED anode; LED cathode → ground (for example, physical pin 6).
- Button: one side → GPIO27; the other side → ground.
Check the pinout for your exact board before connecting anything. Pins may have alternate functions or be in use by another interface, so do not assume every GPIO is interchangeable. GPIO Zero can translate other naming schemes, but sticking to BCM numbers keeps the code and wiring consistent; its recipes explain supported pin-numbering schemes.
Install and verify GPIO Zero
GPIO Zero is included with the Raspberry Pi OS Desktop image according to the project documentation. On Raspberry Pi OS Lite, or if the import check fails, install the distribution package:
sudo apt update
sudo apt install python3-gpiozeroVerify that the Python 3 interpreter you intend to use can import the library:
python3 -c "import gpiozero; print(gpiozero.__version__)"If a project uses a virtual environment, check that the package is available to that environment’s interpreter too. On Raspberry Pi OS, the system package is a sensible default; a virtual environment or another installation method may suit projects with separate dependency requirements. Do not assume a package installed for one Python interpreter is available to another.
Rank #2
- 【Raspberry Pi Pico】 A tiny, fast, and versatile boards built using RP2040, the flagship microcontroller chip designed by Raspberry Pi. Dual-core Arm Cortex-M0+ @ 133MHz; 264KB on-chip SRAM; 2MB on-board QSPI Flash; 26 GPIO pins, including 3 analogue inputs.
- 【Adeept Raspberry Pi Pico GPIO Expansion Board】 Plug-and-Play Hub with I²C/SPI/UART Breakouts; Easy to connect sensors and easy to learn; Integrated DC-DC buck circuit, 4x WS2812 RGB LED and buzzer; Perfect for STEM Education & Industrial Prototyping.
- 【Rich Sensor Modules】34 Sensors, including digital and analog sensors, can be used to build your smart home, smart agriculture, and IoT projects.
- 【Detailed Tutorials】 300+ Pages tutorials, 40 Lessons, step by step guide you to learn the principles and programming of electronic components/sensors.(Paper tutorials are NOT available, download digital tutorials in Adeept website)
- 【Professional Technical Support】 Benefit from our ongoing assistance, including a community forum and timely technical help for a seamless learning experience.
Wire and blink an LED
Build the circuit
With the Pi powered off, connect GPIO17 (physical pin 11) through a 220 Ω or 330 Ω resistor to the LED’s anode. The anode is normally the longer LED leg. Connect the shorter leg, the cathode, to a GND pin such as physical pin 6. The resistor can go on either side of the LED as long as it is in series with it. Do not connect a bare LED directly between a GPIO pin and ground.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Run a Python 3 script
Save the following as blink.py:
from gpiozero import LED
from time import sleep
led = LED(17)
while True:
led.on()
sleep(1)
led.off()
sleep(1)Run it from a terminal in the directory containing the file:
python3 blink.pyThe LED should turn on for about one second and then off for about one second, repeatedly. Press Ctrl+C in the terminal to stop the program. If the GPIO device reports a permission or pin-factory error, troubleshoot that specific error rather than automatically rerunning the program with sudo.
Use GPIO Zero’s blink helper
The library also provides blink(). In a non-interactive script, keep the process alive so the background blinking action can continue:
from gpiozero import LED
from signal import pause
led = LED(17)
led.blink()
pause()Without pause() or another way of keeping the program running, the script reaches its end, exits and releases the GPIO device. The official GPIO Zero recipes show both the direct on/off pattern and helper methods.
Free tools Windows power users keep installed
One-click scans. No signup required.
Read a push button
Connect one button terminal to GPIO27 and the opposite terminal to GND. With its default pull-up arrangement, GPIO Zero treats the button as pressed when the input is pulled to ground, so this wiring does not need an external pull resistor.
Rank #3
- 386 items in total: This complete kit includes the most components, modules, sensors, wires and other items compatible with the Raspberry Pi (NOT included in this kit)
- 5 sets of code: 51 Python examples (compatible with 2&3), 46 C examples, 27 Java examples, 15 Scratch examples and 25 Processing examples (Scratch and Processing examples provide graphical interfaces)
- Detailed tutorial: Can be downloaded (in English, 1170-page in total) or viewed online (original in English, can be translated into other languages by browsers) (The tutorial link can be found on the product box, no paper tutorial)
- 164 projects from simple to complex: Provides step-by-step guide with electronics and components knowledge, each project has schematics, wiring diagrams, complete code and detailed explanations
- Compatible models: Raspberry Pi 5 / 500 / 400 / 4B / 3B+ / 3B / 3A+ / 2B / 1B+ / 1A+ / Zero 2 W / Zero W / Zero (5 not compatible with speaker, 500 / 400 / Zero series not compatible with camera and speaker)
A typical four-leg tactile button has pairs of terminals that are already connected internally; place the button across the breadboard’s centre gap and use terminals on opposite sides. If you use two terminals on the same connected side, pressing the button may not change the circuit as expected.
Save and run this test:
from gpiozero import Button
from signal import pause
button = Button(27)
button.when_pressed = lambda: print("Pressed")
button.when_released = lambda: print("Released")
pause()Pressing and releasing the button should print the corresponding message. Assign a function itself as a callback, not the result of calling it: button.when_pressed = say_hello assigns the function to run later, while button.when_pressed = say_hello() runs it immediately and assigns its return value. See the Button input documentation for the pull-up option and input behavior.
When the button is wired to 3V3 instead
If a button is wired between the GPIO and 3V3 rather than between GPIO and ground, configure the opposite pull arrangement explicitly:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesbutton = Button(27, pull_up=False)Match the software setting to the actual wiring. Do not use 5 V for this alternative.
Make the button control the LED
Keep the LED circuit on GPIO17 and button circuit on GPIO27. This callback version turns the LED on when the button is pressed and off when it is released:
from gpiozero import LED, Button
from signal import pause
led = LED(17)
button = Button(27)
button.when_pressed = led.on
button.when_released = led.off
pause()GPIO Zero also lets one device’s state drive another directly through source:
Rank #4
- 【Updated Starter Kit for Raspberry Pi】This is a updated Assembled starter kit for for Raspberry Pi 4B/3B+/3B/2B/B+, including GPIO Adapter Board with Wiring Diagram Card, 40pin GPIO Rainbow Fat Cable, 830 Tie Points Solderless Breadboard and 65pcs Jumper Wire.
- 【GPIO Adapter Board with Wiring Diagram Card】You can connect much version raspberry of the board to various sensors and electronic components with the GPIO extension board.
- 【40pin GPIO Rainbow Fat Cable】IDC 40pin Male to Female Ribbon Cables Kit flat GPIO Cable; Length: 20 cm; Material: High-quantity copper soft wire material for safe and durable; Easy assembly:The cables can be separated to form an assembly wires to support non-standard odd-spaced headers to complete other tests.
- 【830 Tie Points Solderless Breadboard】made of high quality ABS plastic, each row and columns has corresponding letters and numbers, reduce the mistake handling, with self-adhesive tape on back and multiple links to buckle.
- 【65pcs Flexible Jumper Cables】Flexible, durable, reusable, easy to connect and disconnect; 4 Kinds of length: 12cm(49pcs), 16cm(8pcs), 20cm(4pcs), 24cm(4pcs); these jumper cable wires can connect each other through the pin connection, do not need welding, can fit for fast circuit test.
from gpiozero import LED, Button
from signal import pause
led = LED(17)
button = Button(27)
led.source = button
pause()Use callbacks when you want to learn event-driven programming or perform different actions on press and release. The source form is concise when one input should directly determine one output’s state.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Change LED brightness with PWM
A regular LED is on or off. A PWMLED uses pulse-width modulation (PWM) to switch the output rapidly, which changes the LED’s apparent brightness. Its value ranges from 0 to 1:
from gpiozero import PWMLED
from time import sleep
led = PWMLED(17)
while True:
led.value = 0
sleep(1)
led.value = 0.5
sleep(1)
led.value = 1
sleep(1)Keep the LED’s series resistor in place. PWM does not increase the safe current capacity of a GPIO pin; use an appropriate driver and external supply for larger LED arrays or strips. GPIO Zero’s recipes also include led.pulse() for repeated fading.
Using GPIO Zero on Raspberry Pi 5
Raspberry Pi 5 has a different I/O controller arrangement from earlier boards, so the pin factory matters. GPIO Zero’s pin-factory compatibility table lists lgpio as working across models; it lists RPi.GPIO, pigpio and the native pin factory as not supporting Pi 5.
To see which factory GPIO Zero selected, run:
python3 -c "from gpiozero import Device; print(Device.pin_factory)"If a Pi 5 project reports a pin-factory error, check that a supported lgpio installation is available and avoid forcing an older backend that does not support the board. Pin numbering and backend compatibility are separate issues: LED(17) still means BCM GPIO17, regardless of the factory used. Raspberry Pi’s Pi 5 product information describes its RP1 I/O controller and GPIO access.
Troubleshoot common problems
The LED does not light
- Check that the longer anode leg is toward GPIO17 through the resistor and the cathode goes to ground.
- Confirm that the jumper is on GPIO17, physical pin 11—not physical pin 17—and that the ground wire reaches a GND pin.
- Check that the resistor and LED legs are in separate connected breadboard rows as intended; some breadboard power rails are split.
- Confirm the script is still running and check whether another process is using the pin.
- If the wiring and code are correct, try a known-working LED; the component may be damaged.
The LED is always on or always off
First match the BCM number in the code to the actual GPIO connection. If the LED is wired from 3V3 through the LED and resistor to a GPIO rather than from GPIO to ground, its logic is active-low; GPIO Zero can be told about that arrangement:
Best Value
- 5 sets of code: Python (compatible with 2&3), C, Java, Scratch and Processing (Scratch and Processing code provide graphical interfaces)
- Detailed tutorial: Can be downloaded (in English, 682-page in total) or viewed online (original in English, can be translated into other languages by browsers) (The tutorial link can be found on the product box, no paper tutorial)
- 88 projects from simple to complex: Provides step-by-step guide with electronics and components knowledge, each project has schematics, wiring diagrams, complete code and detailed explanations
- 164 items in total: This kit includes commonly used electronic components, modules, sensors, wires and other compatible items
- Compatible models: Raspberry Pi 5 / 500 / 400 / 4B / 3B+ / 3B / 3A+ / 2B / 1B+ / 1A+ / Zero 2 W / Zero W / Zero (NOT included in this kit)
from gpiozero import LED
led = LED(17, active_high=False)Stop other GPIO programs before retesting so they do not compete for the same pin.
The button appears permanently pressed
- Check that the button straddles the breadboard centre gap and that the two wires use terminals on opposite sides.
- Look for a short between GPIO27 and ground.
- Check that the button’s pull-up configuration matches its wiring: the default is for a button to ground; use
pull_up=Falseonly for a button wired to 3V3.
ModuleNotFoundError: No module named 'gpiozero'
Run the script with python3, then verify that GPIO Zero is installed for that interpreter. On Raspberry Pi OS, install it with sudo apt update followed by sudo apt install python3-gpiozero. If using a virtual environment, check its own interpreter and packages.
BadPinFactory or a pin-factory error
This can occur when running on a computer without Raspberry Pi GPIO hardware, when the selected pin library is missing, or when the selected backend does not support the Pi model. On Pi 5, check the supported lgpio option. For code that needs to be exercised away from a Pi, GPIO Zero provides mock-pin support; see the pin documentation for mock pins and factory selection.
The program will not stop or pins seem to stay in use
Press Ctrl+C in the terminal running the script. If a prior process remains, inspect Python processes before stopping anything:
ps aux | grep pythonIdentify the relevant process and terminate only that process. Repeatedly launching new GPIO scripts can leave multiple programs trying to control the same pins.
What GPIO Zero cannot replace
GPIO Zero provides convenient software controls; it does not change the electrical limits or signal types of the Raspberry Pi. A GPIO input reads a digital state, so an analogue light or temperature sensor generally needs an ADC such as an MCP3008, unless the sensor includes its own digital interface.
- DC motors: use a suitable transistor or H-bridge, with appropriate protection and a motor supply. Do not power the motor from a GPIO pin.
- Servos: GPIO Zero can provide a servo interface, but the servo may need a suitable 5 V supply. Share ground with the Pi when required by the control circuit.
- Relays: use a properly designed driver or module rated for the load; do not connect a relay coil directly to a GPIO pin.
- Addressable LED strips: use suitable level shifting and external power where required, and size the supply for the strip rather than the GPIO.
Where to go next
Once you can map a Python object to a pin and a circuit, build on the same progression: input or output object → GPIO signal → correctly designed circuit → physical response. Try a buzzer, a multi-LED sequence or a digital motion sensor next. For an analogue sensor, add an ADC; for motors or servos, learn the driver and power requirements before wiring the device.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
