Raspberry Pi 5 8GB board

Raspberry Pi 5 GPIO: RPi.GPIO Not Working? Causes and Fixes

Your GPIO code ran fine on a Raspberry Pi 4, but on the Pi 5 it throws an error? Or do you want to check before you switch? This guide shows you how to check which RPi.GPIO you’re running (it takes a minute), what changed on the Raspberry Pi 5 and how to fix each error message.

We reproduced every error message in this article on a Raspberry Pi 5 running the latest Raspberry Pi OS in November 2026 (kernel 6.18, gpiozero 2.0.1, lgpio 0.2.2, rpi-lgpio 0.6).

In short

On the latest Raspberry Pi OS, RPi.GPIO code usually runs on the Pi 5 without changes, because the drop-in replacement rpi-lgpio comes preinstalled.

  • A one-line command shows which RPi.GPIO you’re running.
  • Errors after switching almost always mean Python is loading the original RPi.GPIO (from an older image, or installed via apt or pip), or your venv can’t see the system packages.
  • The fix is either sudo apt install python3-rpi-lgpio or a venv created with --system-site-packages.
  • Don’t install python3-rpi.gpio. For new projects, use gpiozero.

Will Your Code Run on the Pi 5?

First, check which RPi.GPIO package Python actually loads on your system. Run it in the same environment as your script, so inside your activated venv if you use one:

python3 -c "import RPi.GPIO, sys; print('rpi-lgpio' if 'lgpio' in sys.modules else 'original RPi.GPIO')"

If it says rpi-lgpio, your code will almost always run without changes. If it says original RPi.GPIO, your script will fail on the Pi 5 at the first GPIO.setup(). If you get a ModuleNotFoundError, your Python virtual environment (venv) can’t see the system packages. Here are the usual cases:

Your setupWhat Python loadsWhat to do
Raspberry Pi OS image from October 22, 2024 or laterrpi-lgpioNothing to do
Older image (even if fully updated, since updates don’t add rpi-lgpio)Original RPi.GPIO, fails on the Pi 5sudo apt install python3-rpi-lgpio
venv without --system-site-packagesNothing (ModuleNotFoundError)Recreate the venv with --system-site-packages
venv with pip install RPi.GPIOOriginal RPi.GPIO, fails on the Pi 5Rebuild the venv with --system-site-packages (see below)
After sudo apt install python3-rpi.gpioOriginal RPi.GPIO, fails on the Pi 5sudo apt install python3-rpi-lgpio

The change in the image build shows the switch to rpi-lgpio. head -1 /etc/rpi-issue shows the date of your image. If your code runs but some things behave differently, see Where rpi-lgpio Behaves Differently.

Moving from a Pi 4? You can install rpi-lgpio there first with sudo apt install python3-rpi-lgpio. It uses the same /dev/gpiochip kernel interface there, so your setup will be ready when you switch to the Pi 5.

What Changed on the Pi 5

The Pi 5 is the first model with an I/O chip that Raspberry Pi designed in-house: the RP1. It handles most of the I/O, including the GPIO pins, USB, Ethernet and the MIPI connectors for cameras and displays. HDMI, microSD and the PCIe connector still hang off the main BCM2712 processor, which the RP1 connects to over PCIe 2.0 x4 (RP1 datasheet).

The original RPi.GPIO accesses the GPIO registers directly, through /dev/gpiomem or /dev/mem, so it has to know where they are, and it doesn’t know that for the Pi 5. The import still works, but the first GPIO.setup() fails. Here’s what that looks like with RPi.GPIO 0.7.1 installed via pip in a venv (yourname stands for your username):

$ python3 blink.py
Traceback (most recent call last):
  File "/home/yourname/blink.py", line 3, in <module>
    GPIO.setup(18, GPIO.OUT)
    ~~~~~~~~~~^^^^^^^^^^^^^^
RuntimeError: Cannot determine SOC peripheral base address

gpiozero, lgpio and rpi-lgpio use the Linux kernel’s /dev/gpiochip interface instead. Every model has it, which is why the same code runs on the Pi 5 and on older boards. Libraries that use I2C or SPI through the kernel devices /dev/i2c-* and /dev/spidev*, such as smbus2 and spidev, aren’t affected by the change.

Error Messages and How to Fix Them

RuntimeError: Cannot determine SOC peripheral base address

Python is loading the original RPi.GPIO. Install rpi-lgpio with apt. It removes the original for you:

sudo apt update
sudo apt install python3-rpi-lgpio

If pip installed the original into a venv, rebuild the venv with --system-site-packages. These commands save a list of your other packages, delete the old venv, create a new one and reinstall the packages. Replace ~/gpio-env with your own venv folder, and run the commands inside the activated venv:

pip freeze | grep -v -i -E "^(rpi.gpio|rpi-lgpio|lgpio|gpiozero)=" > ~/requirements.txt
deactivate
rm -rf ~/gpio-env
python3 -m venv --system-site-packages ~/gpio-env
source ~/gpio-env/bin/activate
pip install -r ~/requirements.txt
⚠️ pip install rpi-lgpio fails on the latest Raspberry Pi OS

Many older guides tell you to install rpi-lgpio with pip in a fresh venv. On the latest 64-bit Raspberry Pi OS, that fails with error: command 'swig' failed, because there are no prebuilt 64-bit lgpio wheels for Python 3.13 and pip can’t compile the source. Use the apt package and a venv with --system-site-packages instead.

ModuleNotFoundError: No module named 'RPi'

Your script runs in a venv that can’t see the preinstalled packages. With gpiozero, you’ll see No module named 'gpiozero' instead. If the venv has pip packages you want to keep, use the commands from the section above. For a fresh venv, these two lines are enough:

python3 -m venv --system-site-packages ~/gpio-env
source ~/gpio-env/bin/activate

BadPinFactory: Unable to load any default pin factory!

gpiozero can’t find a pin factory, the backend it uses to talk to the pins. Usually your user isn’t in the gpio group (see 'can not open gpiochip' right below), or lgpio is missing from the venv (see ModuleNotFoundError above).

lgpio.error: 'can not open gpiochip'

Usually your user isn’t in the gpio group, which grants access to /dev/gpiochip. The account you created when setting up the Pi is already a member, so this mostly affects newly created users and services. Run groups to check whether gpio is in the list. To add your user:

sudo usermod -aG gpio $USER

Then log out and back in. If the script runs as a service under its own user, use that user’s name instead of $USER and restart the service. If you use lgpio directly, you also get this message when gpiochip_open() is given a chip number that doesn’t exist. Use 0; the details are in lgpio for More Control. gpiozero and rpi-lgpio pick the chip on their own.

lgpio.error: 'GPIO busy'

Something else is already using the pin: a second program, a second gpiochip_open() in the same script that wants the same pin, or a kernel driver. With SPI enabled, GPIO 7 through GPIO 11 belong to the SPI driver. If you’ve turned on 1-Wire, it owns GPIO 4. On the SPI data lines (GPIO 9 to 11), lgpio often reports lgpio.error: 'unexpected error' instead of 'GPIO busy', and xGpioHandleRequest: Invalid argument appears in the console.

Stop the other program, pick a free pin or turn the interface off. To disable SPI, use sudo raspi-config (Interface Options → SPI → No) or add the line dtparam=spi=off to /boot/firmware/config.txt. Turn off 1-Wire in raspi-config (Interface Options → 1-Wire) or remove the dtoverlay=w1-gpio line from config.txt. Then reboot. To see which pins are in use, run gpioinfo (see Checking Which Pins Are in Use).

lgpio.error: 'GPIO not allocated'

You’ll usually see this from GPIO.setup(pin, GPIO.OUT) on a pin that another program or a driver such as SPI already holds. rpi-lgpio reads the pin first and gets this message instead of 'GPIO busy'. If you pass initial= or set the pin up as an input, you get 'GPIO busy' instead. The fix is the same as in the previous section.

If you use lgpio directly, you’ll also get it from gpio_read() on a pin someone else holds, from gpio_free() on a pin you never claimed, and from group_read() or group_write() on pins you haven’t claimed at all. So claim pins first: for reading with gpio_claim_input() or group_claim_input(), for writing with gpio_claim_output() or group_claim_output().

FileNotFoundError: [Errno 2] No such file or directory: '.lgd-nfy-3'

lgpio creates a helper file in the current working directory at startup. If your user can’t write there (for example, in a service with WorkingDirectory=/ or after cd /), the script crashes. The same happens if a file with that name owned by another user is already there, for example in /tmp. This applies to gpiozero and rpi-lgpio too. Start the script from your home directory. For a systemd service, set WorkingDirectory=/home/yourname (with your own username).

raspi-gpio: command not found

The old raspi-gpio tool is gone from the current Raspberry Pi OS, and it never worked on the Pi 5 anyway: on older images it just says raspi-gpio is not supported on Pi 5 - use `pinctrl`. Its replacement, pinctrl, comes preinstalled and uses the same syntax. You can usually even leave out get and set:

pinctrl get 17        # instead of raspi-gpio get 17
pinctrl set 17 op dh  # instead of raspi-gpio set 17 op dh

With pinctrl -p, you refer to pins by their number on the 40-pin header instead of the GPIO number. To find pins that are already in use, see Checking Which Pins Are in Use.

Checking Which Pins Are in Use

The preinstalled gpioinfo from the gpiod package shows which lines (the kernel’s name for pins) are in use. On the Pi 5, just like on older models, the header pins are listed under gpiochip0:

gpioinfo -c 0

Lines in use show consumer="…" with the name of the driver or program, while free lines have no extra label. Kernel interfaces such as I2C or the SPI data lines often just show kernel. In this example, SPI holds GPIO 7, 8 and 9 (among other pins), while GPIO 17 and GPIO 27 are free:

gpiochip0 - 54 lines:
	line   0:	"ID_SDA"        	input consumer="kernel"
	line   1:	"ID_SCL"        	input consumer="kernel"
	line   2:	"GPIO2"         	input consumer="kernel"
	...
	line   7:	"GPIO7"         	output active-low consumer="spi0 CS1"
	line   8:	"GPIO8"         	output active-low consumer="spi0 CS0"
	line   9:	"GPIO9"         	input consumer="kernel"
	...
	line  17:	"GPIO17"        	input
	...
	line  27:	"GPIO27"        	input

If older guides show unused and [used] instead, that’s the output format of the previous gpiod version. To see how individual pins are currently set up, use pinctrl:

pinctrl get 8,17
 8: op dh pu | hi // GPIO8 = output
17: no    pd | -- // GPIO17 = none

Here, GPIO 8 is an output (op) currently driving high (dh, level hi), with its pull-up on (pu). GPIO 17 has no function set (no); only its pull-down resistor is enabled (pd).

Leave GPIO 0 and GPIO 1 alone

GPIO 0 and GPIO 1 (shown in gpioinfo as ID_SDA and ID_SCL) are reserved on every Raspberry Pi with a 40-pin header so HATs can be detected automatically through their EEPROM. Don’t use them as regular GPIOs, whichever library you use.

Which Library Should I Use?

Your situationLibraryWhy
Existing RPi.GPIO coderpi-lgpioPreinstalled, your code stays as it is
New projectgpiozeroSimplest syntax, preinstalled, runs on every model
Full control over pins and eventslgpioYou claim every pin yourself, callbacks and PWM included
Original RPi.GPIODon’t use it anymoreDoesn’t run on the Pi 5, last release in 2022 (PyPI)

pigpio, once popular for precise timing, doesn’t run on the Pi 5 either. If you used it, switch to gpiozero or lgpio. For servos and other timing-critical jobs, there’s hardware PWM through an overlay, as described in our guide to GPIO with Python. For most projects, gpiozero is the best choice: less code, and you never have to think about chip numbers or GPIO.cleanup().

rpi-lgpio: Keep Using Your Existing Code

rpi-lgpio is a drop-in replacement for RPi.GPIO: it offers the same API but uses lgpio under the hood, which means it goes through the /dev/gpiochip interface. The latest Raspberry Pi OS already has it installed, so import RPi.GPIO picks up rpi-lgpio automatically. On older systems, sudo apt install python3-rpi-lgpio is all you need, and you don’t have to remove the original package first. The venv commands are in Error Messages and How to Fix Them above.

Example: Blinking an LED with RPi.GPIO

With rpi-lgpio, a typical RPi.GPIO script like this LED blinker runs on the Pi 5 unchanged. For this example, connect an LED with a 220–330 Ω resistor in series between GPIO 18 and GND:

import RPi.GPIO as GPIO
import time

GPIO.setmode(GPIO.BCM)
GPIO.setup(18, GPIO.OUT)

try:
    while True:
        GPIO.output(18, GPIO.HIGH)
        time.sleep(1)
        GPIO.output(18, GPIO.LOW)
        time.sleep(1)
except KeyboardInterrupt:
    GPIO.cleanup()

Where rpi-lgpio Behaves Differently

rpi-lgpio isn’t a perfect copy. Its developer lists a few differences:

  • Claimed pins: The original could access pins held by another program or a kernel driver such as SPI. rpi-lgpio can’t; it reports 'GPIO busy', 'GPIO not allocated' or 'unexpected error' instead (see Error Messages).
  • Debouncing: rpi-lgpio only reports an edge once the signal has been stable for bouncetime. This means edges arrive slightly later, and pulses shorter than bouncetime are missed entirely.
  • gpio_function() only reports IN or OUT, never SPI, I2C or HARD_PWM.
  • PWM on exit: After pwm.stop() and GPIO.cleanup(), you may see a TypeError from PWM.__del__ as the script exits. It’s harmless, since the script has already finished its work by then.

The full list of differences is in the rpi-lgpio docs.

For new projects, use gpiozero. It’s what the official Raspberry Pi documentation uses for Python, it comes preinstalled, and it runs on every model. On the Pi 5, it picks lgpio as its backend and finds the right chip on its own, so you don’t have to set a pin factory or a chip number:

from gpiozero import LED, Button
from signal import pause

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

button.when_pressed = led.on
button.when_released = led.off

pause()

To try it out, you need an LED with a 220–330 Ω resistor in series between GPIO 18 and GND, plus a push button between GPIO 17 and GND. Plug everything into a breadboard* and connect it with jumper wires*. The Freenove Starter Kit* includes everything you need. For more examples with PWM, buttons and running scripts at boot, see our guide to GPIO with Python.

Links marked with * are affiliate links, which makes them advertising. If you buy through one, I earn a commission at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Learn more

lgpio for More Control

If you want to claim every pin yourself, use lgpio directly. It takes more code but gives you full control over pins and events:

import lgpio
import time

LED_PIN = 18

h = lgpio.gpiochip_open(0)   # chip 0 = header GPIOs, Pi 5 included
lgpio.gpio_claim_output(h, LED_PIN)

try:
    while True:
        lgpio.gpio_write(h, LED_PIN, 1)
        time.sleep(1)
        lgpio.gpio_write(h, LED_PIN, 0)
        time.sleep(1)
except KeyboardInterrupt:
    pass
finally:
    lgpio.gpio_write(h, LED_PIN, 0)
    lgpio.gpiochip_close(h)

Older guides use lgpio.gpiochip_open(4), because that was the chip’s number on the Pi 5 before kernel 6.6.45. What matters is the running kernel, not the image: if you updated an old system with apt, you’ll have gpiochip0 as well. On the latest Raspberry Pi OS, both numbers work, because it adds a /dev/gpiochip4 link for older code. Use 0 for anything new. If uname -r shows a version below 6.6.45, run sudo apt full-upgrade and reboot to get the new kernel, and 0 applies from then on; without the update, use 4 there. Our guide to GPIO with Python covers callbacks and software PWM with lgpio.

Wrapping Up

The RP1 changed GPIO on the Raspberry Pi 5, but most of you will barely notice: on the latest Raspberry Pi OS, RPi.GPIO code keeps running through rpi-lgpio. Errors after switching almost always come from the original package or from a venv without system packages, and a single apt command or a fresh venv fixes them. If you’re starting a new project, go straight to gpiozero.

To see which pins the Pi 5 has and what they can do, check out our interactive GPIO pinout tool.

Frequently Asked Questions About GPIO on the Raspberry Pi 5

Why doesn’t RPi.GPIO work on the Raspberry Pi 5?

The original RPi.GPIO accesses the GPIO registers directly. On the Pi 5, the pins sit on the new RP1 I/O chip, which the package doesn’t support, so GPIO.setup() fails with Cannot determine SOC peripheral base address. On the latest Raspberry Pi OS, though, import RPi.GPIO loads the rpi-lgpio replacement, so your code runs anyway.

Will my old RPi.GPIO code run on the Raspberry Pi 5?

Usually, yes. On the latest Raspberry Pi OS it runs without changes, because rpi-lgpio comes preinstalled. The check command in this article tells you whether Python loads rpi-lgpio or the original. On older systems, run sudo apt install python3-rpi-lgpio. If you use a venv, recreate it with --system-site-packages.

Do I have to rewrite all my GPIO code for the Raspberry Pi 5?

No. With rpi-lgpio, existing RPi.GPIO code runs unchanged in the vast majority of cases. The main differences concern pins already held by another program or driver, debouncing, and a few details such as gpio_function(). Switching to gpiozero is only worth it for new projects.

Does gpiozero work on the Raspberry Pi 5?

Yes. gpiozero comes preinstalled, picks lgpio as its backend on the Pi 5 and finds the right GPIO chip by itself. You don’t need to set a pin factory or chip number.

Do I need to disable SPI for rpi-lgpio?

Only if you want to use the SPI pins as regular GPIOs. With SPI enabled, GPIO 7 through GPIO 11 belong to the SPI driver, and rpi-lgpio reports an error such as 'GPIO busy' or 'GPIO not allocated' for them. You can turn SPI off in raspi-config or with dtparam=spi=off in config.txt, followed by a reboot. If you don’t need those pins, just leave SPI on.

Similar Posts