{"id":6657,"library":"gpiod","title":"Python bindings for libgpiod","description":"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.","status":"active","version":"2.4.2","language":"en","source_language":"en","source_url":"https://github.com/brgl/libgpiod","tags":["gpio","linux","hardware","raspberrypi","embedded","bindings"],"install":[{"cmd":"pip install gpiod","lang":"bash","label":"Standard installation"},{"cmd":"sudo apt install python3-dev\npip install gpiod","lang":"bash","label":"Required for building from source (Debian/Ubuntu)"},{"cmd":"LINK_SYSTEM_LIBGPIOD=1 pip install gpiod","lang":"bash","label":"Optional: Link against system libgpiod"}],"dependencies":[{"reason":"Required for building the bindings from source, as binary wheels are not provided.","package":"python3-dev","optional":false}],"imports":[{"symbol":"gpiod","correct":"import gpiod"},{"note":"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).","wrong":"import gpiod.chip","symbol":"Chip","correct":"from gpiod import Chip"},{"symbol":"LineSettings","correct":"from gpiod.line import LineSettings"},{"symbol":"Direction","correct":"from gpiod.line import Direction"},{"symbol":"Value","correct":"from gpiod.line import Value"}],"quickstart":{"code":"import time\nimport os\nfrom gpiod import Chip\nfrom gpiod.line import Direction, Value, LineSettings\n\n# NOTE: For Raspberry Pi 5, use '/dev/gpiochip4'. For Pi 4 and older, use '/dev/gpiochip0'.\nGPIO_CHIP_PATH = os.environ.get('GPIO_CHIP_PATH', '/dev/gpiochip0')\nGPIO_LINE_OFFSET = int(os.environ.get('GPIO_LINE_OFFSET', '17')) # Example offset, replace with your actual GPIO pin number\n\ndef blink_gpio(chip_path: str, line_offset: int, num_blinks: int = 5, delay: float = 0.5):\n    try:\n        with Chip(chip_path) as chip:\n            print(f\"Accessing GPIO chip: {chip.name} [{chip.label}] ({chip.num_lines} lines)\")\n\n            # Request the line for output\n            line_settings = LineSettings(direction=Direction.OUTPUT)\n            # Use a dictionary for request_lines config\n            config = {line_offset: line_settings}\n            \n            # Using request_lines to get a LineRequest object\n            with chip.request_lines(consumer=\"quickstart_blinker\", config=config) as request:\n                print(f\"Blinking GPIO line {line_offset}...\")\n                for i in range(num_blinks):\n                    request.set_value(line_offset, Value.ACTIVE)\n                    print(f\"[{i+1}/{num_blinks}] Line {line_offset} HIGH\")\n                    time.sleep(delay)\n                    request.set_value(line_offset, Value.INACTIVE)\n                    print(f\"[{i+1}/{num_blinks}] Line {line_offset} LOW\")\n                    time.sleep(delay)\n                print(\"Blinking complete.\")\n\n    except FileNotFoundError:\n        print(f\"Error: GPIO chip '{chip_path}' not found. Ensure it exists and you have permissions.\")\n    except PermissionError:\n        print(f\"Error: Permission denied to access '{chip_path}'. Try running with 'sudo'.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    blink_gpio(GPIO_CHIP_PATH, GPIO_LINE_OFFSET)\n","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure 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`).","message":"The `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.","severity":"breaking","affected_versions":"<2.0.2"},{"fix":"Before `pip install gpiod`, ensure system dependencies are met: `sudo apt install python3-dev` (on Debian/Ubuntu) or equivalent for your distribution.","message":"Building `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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.","message":"The 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`.","severity":"gotcha","affected_versions":"All versions, platform-dependent"},{"fix":"Always 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.","message":"GPIO 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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`.","message":"Permissions issues are common when accessing `/dev/gpiochipX` devices, especially when running Python scripts as a regular user.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}