Future-proof Blinka

[makermelissa]

Blinka currently uses setup.py, which is now deprecated. However, because it runs on a wide variety of processors and Linux environments. switching to pyproject.toml is a bit complicated. There is a way to have different variations of the installer, but because Blinka is listed as a dependency on CircuitPython libraries that may be used on several board, there isn't a one-size-fits-all option.

The goal of this issue is to put it in a state where it can meet all of these requirements:

• Move over to a setup system that isn't deprecated
• Allow Blinka to be listed as a dependency and install (or direct) the user to install appropriately on the environment
• Still work on a bunch of boards
• Possibly move to a newer version of Python (such as Python 3.9)

[makermelissa-ai-assistant]

I've been prototyping this on a local branch (pyproject-migration) and wanted to share findings and a proposed approach.

What we ruled out

pip install adafruit-blinka[rpi] extras — looks clean but breaks the transitive install case. Every pip install adafruit-circuitpython-<anything> tutorial pulls in adafruit-blinka as a dependency without users ever typing the package name. Extras don't propagate through transitive deps, so users would get a broken install with no clear error. This is a hard constraint: pip install <any-CP-library> must produce a working import board on the target hardware with zero extras knowledge required.

Debian packaging (apt install python3-blinka) — would solve PEP 668 externally-managed-environment issues cleanly, but the ITP process takes months, requires packaging every dependency, and demands ongoing maintenance. Out of scope for now.

What works: PEP 508 markers + runtime sanity check

The empirical situation is better than it looks. Most of the feared "wrong-platform compile failures" don't actually happen because the ARM-specific deps (RPi.GPIO, rpi-ws281x) do their platform check at runtime (reading /proc/cpuinfo for BCM strings), not at build time — they'll compile fine on x86 as harmless dead weight. So a pyproject.toml with sys_platform/platform_machine markers works as a wheel-metadata-only superset approach.

The one real problem child: Adafruit_BBIO — its sdist bootstrap uses a Python 2-era TarFile.chown() call that's broken on Python 3.12+ everywhere. This is an upstream issue, not a Blinka issue, and should be tracked separately. Workaround in markers: gate it on python_version < '3.12'.

lgpio on Python 3.13+ — the PyPI wheel for lgpio was built for cp313 but the metadata tags it wrong, causing pip to reject it. The sdist builds fine from source. Adafruit has a working wheel repo at adafruit/lgpio-python-wheels that we can point users to.

Proposed pyproject.toml dependency markers

dependencies = [
    "Adafruit-PlatformDetect>=3.70.1",
    "Adafruit-PureIO>=1.1.7",
    "binho-host-adapter>=0.1.6",
    "pyftdi>=0.40.0",
    "adafruit-circuitpython-typing",
    "toml>=0.10.2; python_version < '3.11'",
    "sysv_ipc>=1.1.0; sys_platform == 'linux' and platform_machine != 'mips'",
    "Jetson.GPIO; sys_platform == 'linux' and platform_machine == 'aarch64'",
    "rpi_ws281x>=4.0.0; sys_platform == 'linux' and (platform_machine == 'armv6l' or platform_machine == 'armv7l' or platform_machine == 'aarch64')",
    "lgpio>=0.2.2.0; sys_platform == 'linux' and python_version < '3.13' and (platform_machine == 'armv6l' or platform_machine == 'armv7l' or platform_machine == 'aarch64')",
    "RPi.GPIO; sys_platform == 'linux' and (platform_machine == 'armv6l' or platform_machine == 'armv7l' or platform_machine == 'aarch64')",
    "Adafruit-Blinka-Raspberry-Pi5-Neopixel; sys_platform == 'linux' and platform_machine == 'aarch64' and python_version >= '3.11'",
    # Adafruit_BBIO 1.2.0 sdist uses a Python 2-era TarFile.chown() — broken on 3.12+
    "Adafruit_BBIO; sys_platform == 'linux' and platform_machine == 'armv7l' and python_version < '3.12'",
]

requires-python = ">=3.9" — locks out Jetson Nano JetPack 4 (Python 3.6/3.8) and similarly frozen platforms, but those are upgrade-frozen for non-Blinka reasons already.

Bonus: runtime sanity check

Because PEP 508 markers can't read /proc/device-tree/compatible, a Pi 5 running Python 3.13 won't get lgpio from the markers above (Py3.13 gate). The wheel metadata is correct, but the user is silently under-installed.

A small _platform_check.py module — called at the top of board.py, digitalio.py, busio.py, and the other entry-point modules — can detect this at import time and raise a clear ImportError with the exact install command for the missing dep (including the Adafruit wheel URL for lgpio on Pi 5 + Py3.13+). Env-var escape hatch (BLINKA_SUPPRESS_PLATFORM_CHECK=1) for CI/cross-compile scenarios.

This is also useful independently of the pyproject.toml migration — it catches --no-deps installs, stale venvs, and Docker images that stripped a dep for size.

Confirmed broken today (baseline on fresh Pi 5, Py3.13)

PyPI adafruit-blinka 9.1.0:

• Install: SUCCESS
• lgpio: NOT installed (conditional dep evaluated to empty when the wheel was built on CI — this is issue uv pip fails to install necessary packages #916)
• import board → ModuleNotFoundError: No module named 'lgpio'

This isn't a future-Python problem. It's broken today on the most current Pi with the most current Pi OS image.

PR plan

Two PRs:

1. Sanity check only — _platform_check.py + one-line import in each entry-point module. Ships independently, helps users on current Blinka immediately, zero packaging risk.
2. pyproject.toml migration — replaces setup.py runtime probe with wheel metadata markers, bumps requires-python to >=3.9. Closes uv pip fails to install necessary packages #916.

Happy to open these once the approach looks good.

[makermelissa]

Possibly relevant issue: #1016

[makermelissa]

Other BeagleBone related issues:
adafruit/adafruit-beaglebone-io-python#373
adafruit/adafruit-beaglebone-io-python#374
adafruit/adafruit-beaglebone-io-python#362

[makermelissa-ai-assistant]

The BeagleBone links make Adafruit_BBIO look like a separate upstream dependency track for this migration rather than just a Blinka marker decision.

Relevant issues:

• sudo pip3 install Adafruit_BBIO fails on Python >= 3.9 adafruit-beaglebone-io-python#362: Python 3.9+ build failure; fixed by PR Added SoPine compatibility #366, merged in 2023.
• Adafruit_BBIO not installing with Python 13.1 adafruit-beaglebone-io-python#373: Python 3.13 install/build failure on BeagleBone Black; still open.
• ADAFRUIT_BBIO Fails to install out of the box on debian 13. adafruit-beaglebone-io-python#374: Debian 13 / newer GCC build failure due to missing sys/time.h; still open and likely straightforward to fix.

For the initial Blinka pyproject.toml migration, it may still be safest to gate Adafruit_BBIO conservatively until a fixed Adafruit_BBIO release is available:

"Adafruit_BBIO; sys_platform == 'linux' and platform_machine == 'armv7l' and python_version < '3.12'"

Then, after adafruit-beaglebone-io-python has a release that builds cleanly on newer Python/Debian combinations, Blinka can loosen that marker and depend on the fixed version.

That lets the Blinka packaging migration move forward without losing track of BeagleBone support; the BeagleBone work becomes a parallel unblocker rather than a permanent limitation.

[makermelissa-ai-assistant]

Update on Adafruit_BBIO: the Python 3.12+ build issue is now fixed. PR #377 (merged 2026-06-18) removed distribute_setup.py and added pyproject.toml, and release 1.2.4 (2026-06-23) includes additional fixes for newer BBB Debian releases.

The python_version < '3.12' gate in the proposed markers can be dropped. The dependency entry becomes simply:

"Adafruit_BBIO>=1.2.1; sys_platform == 'linux' and platform_machine == 'armv7l'"

[makermelissa]

Fixed by #1114.