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.
Chip
✓ from gpiod import Chip
✗ import gpiod.chip
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).
LineSettings
✓ from gpiod.line import LineSettings
Direction
✓ from gpiod.line import Direction
Value
✓ 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
Debug
Known issues
breakingThe `gpiod` library underwent a major breaking change with version 2.0.2. This version replaced an older, unofficial pure-Python implementation (versions 1.5.4 and prior) with official C-bindings to `libgpiod`. The APIs are not backwards compatible.fixEnsure your `pip install` command specifies `gpiod>=2.0.2` to get the official bindings. If migrating from older code, refactor imports and usage patterns according to the v2+ API (e.g., `gpiod.Chip` instead of `gpiod.chip`).
affects: <2.0.2
gotchaBuilding `gpiod` from source (which is often required as binary wheels are not provided) necessitates the `python3-dev` package (or equivalent development headers for Python). Without it, installation will fail.fixBefore `pip install gpiod`, ensure system dependencies are met: `sudo apt install python3-dev` (on Debian/Ubuntu) or equivalent for your distribution.
affects: All versions
gotchaThe path to the GPIO character device (`/dev/gpiochipX`) varies between different hardware platforms. Specifically, Raspberry Pi 5 typically uses `/dev/gpiochip4` for external GPIOs, while older Raspberry Pi models (e.g., Pi 4, Pi 3, Pi Zero) commonly use `/dev/gpiochip0`.fixAlways verify the correct GPIO chip path for your specific hardware using `gpioinfo` (a command-line tool from `libgpiod`) or by inspecting `/dev/gpiochip*` files. Update your code's `chip_path` accordingly.
affects: All versions, platform-dependent
gotchaGPIO line objects (`gpiod.Chip` and `gpiod.LineRequest`) manage system resources (file descriptors). Failure to close these resources can lead to resource leaks and prevent other processes from accessing the GPIOs.fixAlways use `gpiod.Chip` and `gpiod.LineRequest` objects within a `with` statement. This ensures that resources are properly acquired and released automatically, even if errors occur.
affects: All versions
gotchaPermissions issues are common when accessing `/dev/gpiochipX` devices, especially when running Python scripts as a regular user.fixEnsure the user running the script has appropriate permissions to access the GPIO character devices. This may involve adding the user to a specific group (e.g., `gpio` on some systems) or, as a temporary measure for testing, running the script with `sudo`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gpiod'
The 'gpiod' Python package is not installed or is not accessible in the current Python environment. This can happen due to incorrect installation, issues with virtual environments, or conflicts with system-level `libgpiod` installations.
fixEnsure the package is installed using `pip install gpiod`. If using a virtual environment, activate it and install `gpiod` within it. If `python3-libgpiod` was installed via `apt`, consider creating the virtual environment with `python -m venv --system-site-packages env` to inherit system packages, or rely solely on `pip install gpiod` for the official bindings.
AttributeError: module 'gpiod' has no attribute 'Chip'
This error often occurs when code written for a newer version of the `gpiod` library (official bindings, v2.0.2+) is executed with an older, deprecated pure-Python `gpiod` library (v1.5.4 and prior), or when there's a mix-up in installations.
fixEnsure you have the latest official `gpiod` bindings installed by running `pip install --upgrade gpiod`. The current version (2.4.2) supports `gpiod.Chip` (capital 'C'). If you intended to use the old pure-Python library, you would typically use `gpiod.chip` (lowercase 'c'), but it's recommended to migrate to the official bindings.
FileNotFoundError: [Errno 2] No such file or directory (when opening gpiochip)
The string provided to `gpiod.Chip()` is not a valid path to a GPIO chip device. Users often provide just the chip name (e.g., 'gpiochip0') instead of the full device path expected by the library.
fixUse the full device path for the GPIO chip, typically `'/dev/gpiochipX'` (e.g., `chip = gpiod.Chip('/dev/gpiochip0')`). You can find available chip paths using commands like `ls /dev/gpiochip*` or `gpioinfo` on your system. Permission denied (when accessing GPIOs)
The user running the Python script lacks the necessary permissions to access the `/dev/gpiochipX` device files, which control the GPIO pins. Direct GPIO access often requires root privileges or membership in specific user groups.
fixAdd your user to the 'gpio' and/or 'dialout' user groups (e.g., `sudo usermod -a -G gpio <your_username>` and `sudo usermod -a -G dialout <your_username>`) and then reboot your system for the changes to take effect. Alternatively, run the script with `sudo`, but this is generally less secure.
Upgrade
Version history
2.4.2latest on PyPI · released Apr 9, 2026
Audit
Dependencies
python3-devrequiredRequired for building the bindings from source, as binary wheels are not provided.