Roadmap: towards caniuse for Python wheels

[patrickballard]

wheelgap started as a small CLI that answers one question: which of my dependencies have no prebuilt wheel for the platforms I ship to? In its first two days it gained six contributors (thank you @nodearray, @jwalith4418-Mj, @Swarneil1905, @Daiyuanranfeng, @draarivpatel-ui and @O1sumitkumar) and four releases, adding lockfile support for uv, Poetry, PDM, Pipenv and pylock, Docker-aware targets, Pyodide, pre-commit, and a GitHub Action.

This post is about where it goes next. Comments, objections and better ideas are very welcome below.

Update, 9 November: most of Phase 1 is done. The tracker is live and rescans the top 5,000 packages every night, and wheelgap has moved into the wheelgap organisation. Every step that's ready for help now has an issue, labelled roadmap and filed under a milestone per phase (and in the tracker repo). Each issue links back here.

The idea: caniuse, but for Python wheels

Web developers have caniuse.com: one place to ask "does this work in that browser?". Python has no equivalent for the question we keep running into:

Can I install package X on platform Y? Linux ARM, Alpine, Windows on ARM, free-threaded Python, Pyodide in the browser, iOS and Android, riscv64…

That question gets more common every year. Each new Python release, platform and ABI adds another column, and today the answers are spread across one-question trackers, issue threads and Dockerfile comments.

So the plan is to grow wheelgap from a CLI into an open, community-maintained map of Python wheel coverage, with the CLI as one way to use it:

1. The engine (exists today): the CLI and a Python library that decide, for a package and a target, whether there's a wheel, an sdist build, or nothing.
2. The tracker: a nightly scan of the most-used PyPI packages across every target, published as an open dataset and a website, with a page per package and per platform.
3. The knowledge base: what automation can't know, written by people. "Use psycopg[binary] instead." "Add libpq-dev to your image." "Pyodide bundles this." "Upstream is tracking it in issue docs: add a free-threading readiness recipe #123." Small, reviewed files that anyone can add, shown in the CLI's --explain output and on the site.
4. Campaigns: the tracker turns missing wheels into a to-do list, so we can help upstream projects ship them, usually with cibuildwheel, and watch coverage climb. That always means working with upstream maintainers: asking first and respecting a "not now", never mass-filing issues.

Phases

Dates are aims, not promises.

Phase 1: the tracker (aiming for December 2026)

• A small, documented Python API, e.g. wheelgap.check_package("numpy", "2.3.4", targets=[...]), so the scanner and other tools don't go through the CLI Shipped in 0.4.0.
• A scanner that checks the latest release of the top ~5,000 PyPI packages (from the top-pypi-packages dataset) against every target, run nightly by GitHub Actions Shipped in 0.4.0 (python -m wheelgap.scan); runs every night.
• The results as an open dataset (JSON, versioned in git, so history is free): coverage.json, CC0
• A static website: live at wheelgap.github.io/tracker, with coverage by platform, package lookup and gap lists
• A page per package, so search engines can find them (tracker#3)
• Coverage over time, from the nightly history (tracker#1)
• Coverage badges that package maintainers can put in their README (via a shields.io endpoint) (tracker#2)

Phase 2: the knowledge base (early 2027)

• A schema for notes (one small YAML file per package/platform): workarounds, alternative packages, links to upstream tracking issues, where else a build exists (conda-forge, Pyodide). Proposals wanted: Propose the format for community notes (knowledge base) #50
• CI that validates notes, so reviews stay quick
• Notes shown in wheelgap --explain and on the site, with an "add a note" link on every gap
• Pyodide's bundled packages and other non-PyPI sources folded into the data (building on --pyodide-lock) (Scanner: count packages Pyodide bundles itself #49)

Phase 3: campaigns and integrations (2027)

• Coverage campaigns, e.g. "musllinux aarch64 wheels for the top 500", with a tracking board and a how-to for adding wheels upstream
• A dependency-update guard: the GitHub Action compares two lockfiles and comments on Dependabot/Renovate PRs when a bump drops a platform. First step: wheelgap diff (wheelgap diff: new gaps between two lockfiles #51)
• GitHub job summaries (Write the gap table to the GitHub Actions job summary #7) and other CI-friendly output

Ongoing: more platforms, more inputs

• iOS and Android (iOS and Android targets (PEP 730 / PEP 738) #11), more Linux architectures (Add armv7l, ppc64le, s390x and riscv64 Linux targets #8), Python 3.15 and free-threaded 3.15t (Scanner: check Python 3.15 and 3.15t by default #46)
• Private package indexes (Private indexes via the simple API (--index-url, PEP 691) #19)
• "Nearest version with a wheel" hints (Suggest the nearest version that has a wheel (--suggest) #20)
• The CLI improvements in the good first issues

How the project will be run

• The CLI stays focused. It does one job well. The project grows around it, through the data, the site and the integrations, not by piling features onto the command.
• Small contributions are first-class. Most of the tracker's value will come from many small notes and upstream fixes, not just core code.
• Areas, with owners. wheelgap now lives in its own GitHub organisation, github.com/wheelgap, with separate areas for the engine, the data, the site and campaigns. Each area gets its own code owners, so reviews don't bottleneck on one person.
• A path to maintainer. Regular contributors will be invited to help triage, and then to maintain an area. If that interests you, say so below.
• Fast reviews. The aim is a first review within a day, as now.

How you can help right now

• Python developers: pick a good first issue, or say below that you'd like to work on the scanner or the API.
• Web developers: the site is a greenfield static site. If you'd like to shape it, say hi below.
• Packaging people: tell us which platforms and packages hurt most. That decides what the tracker and the first campaigns cover.
• Everyone: use wheelgap in your CI, and report anything it gets wrong.

Questions, ideas and disagreements are all welcome in the replies, or in Ideas.

Patrick