gpiod provides official Python bindings for `libgpiod`, a library designed for interacting with the modern Linux GPIO character device interface. This package bundles `libgpiod` for convenience, making it independent of the system's `libgpiod` installation. It replaces the older, obsolete sysfs interface by offering a robust way to control GPIO pins, read input values, set outputs, and monitor events with advanced features like event polling and setting multiple values. The current version is 2.4.2, and it is actively maintained.
Install & Compatibility
Where this runs
tested against v2.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.057s · 18.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.053s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
As of v2.0.2, the main Chip class is accessed directly from the `gpiod` module or imported as `gpiod.Chip` (uppercase). Older, unofficial pure-Python bindings (v1.5.4 and prior) used `gpiod.chip` (lowercase).
from gpiod import Chip
from gpiod.line import LineSettings
from gpiod.line import Direction
from gpiod.line import Value
This example demonstrates how to set a GPIO line to an output direction and toggle its state (blink). It uses the `with` statement for proper resource management and highlights the common chip path and line offset configuration. Remember to replace `GPIO_LINE_OFFSET` with an actual GPIO pin number on your device. For Raspberry Pi 5, the GPIO chip is typically `/dev/gpiochip4`, while for older models (Pi 4, 3, Zero), it's usually `/dev/gpiochip0`.
import time
import os
from gpiod import Chip
from gpiod.line import Direction, Value, LineSettings
# NOTE: For Raspberry Pi 5, use '/dev/gpiochip4'. For Pi 4 and older, use '/dev/gpiochip0'.
GPIO_CHIP_PATH = os.environ.get('GPIO_CHIP_PATH', '/dev/gpiochip0')
GPIO_LINE_OFFSET = int(os.environ.get('GPIO_LINE_OFFSET', '17')) # Example offset, replace with your actual GPIO pin number
def blink_gpio(chip_path: str, line_offset: int, num_blinks: int = 5, delay: float = 0.5):
try:
with Chip(chip_path) as chip:
print(f"Accessing GPIO chip: {chip.name} [{chip.label}] ({chip.num_lines} lines)")
# Request the line for output
line_settings = LineSettings(direction=Direction.OUTPUT)
# Use a dictionary for request_lines config
config = {line_offset: line_settings}
# Using request_lines to get a LineRequest object
with chip.request_lines(consumer="quickstart_blinker", config=config) as request:
print(f"Blinking GPIO line {line_offset}...")
for i in range(num_blinks):
request.set_value(line_offset, Value.ACTIVE)
print(f"[{i+1}/{num_blinks}] Line {line_offset} HIGH")
time.sleep(delay)
request.set_value(line_offset, Value.INACTIVE)
print(f"[{i+1}/{num_blinks}] Line {line_offset} LOW")
time.sleep(delay)
print("Blinking complete.")
except FileNotFoundError:
print(f"Error: GPIO chip '{chip_path}' not found. Ensure it exists and you have permissions.")
except PermissionError:
print(f"Error: Permission denied to access '{chip_path}'. Try running with 'sudo'.")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == '__main__':
blink_gpio(GPIO_CHIP_PATH, GPIO_LINE_OFFSET)
gpiodetect --version
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.