wheelgap

Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does.

Point it at your lockfile and the platforms you ship to (ARM servers, Alpine images, Windows on ARM, free-threaded Python 3.14t). It tells you which packages pip or uv will have to compile from source, and which can't be installed at all.

Install and run (under 30 seconds)

With uv:

uvx wheelgap

Or with pipx:

pipx run wheelgap

Or install it: pip install wheelgap.

Run either one in a project directory. It finds uv.lock, pylock.toml, poetry.lock or requirements.txt on its own.

Usage

# Will my Alpine ARM image compile anything?
wheelgap -p 3.13 -t alpine-arm64

# Is my stack ready for free-threaded Python 3.14?
wheelgap -p 3.14t -t all

# Several Pythons at once, Linux on both architectures
wheelgap uv.lock -p 3.12,3.13,3.14 -t linux-x86_64,linux-aarch64

# No lockfile? Check packages directly (latest version, or pin one)
wheelgap psycopg2 uvloop numpy==2.3.4 -t windows,win-arm64

# Machine-readable, for scripts and CI
wheelgap --json > wheelgap.json

# Why is it a gap? List each rejected wheel and the reason
wheelgap -t alpine-arm64 --explain

Each cell in the table is one of:

Packages that are fine everywhere are hidden; --all shows them.

--explain lists, for each gap, the wheels that were rejected and why, closest misses first:

armlib 1.4.0 on musl-aarch64: ● source
  armlib-1.4.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl  manylinux_2_17_aarch64 is a glibc wheel; musl (Alpine) needs musllinux

If you think wheelgap got a package wrong, that output (or --json --explain) is all a bug report needs, with no need to share your lockfile.

Exit codes: 0 no gaps, 1 gaps found, 2 bad input. --exit-zero always exits 0.

Targets

-t all checks all eight. Python versions take a trailing t for free-threaded builds (3.14t), which correctly rejects abi3 wheels. Without -p, wheelgap uses the Python it is running on.

In CI (GitHub Action)

- uses: actions/checkout@v7
- uses: patrickballard/wheelgap@v0.1.1
  with:
    args: uv.lock -p 3.13 -t linux-x86_64,linux-aarch64

The job fails when a dependency would build from source on a target you ship, for example when a dependency bump drops ARM wheels.

How it works

• Lockfiles are read offline. uv.lock, pylock.toml and poetry.lock already record every file published for each pinned version. wheelgap parses the wheel filenames' tags with packaging and checks them against the exact tag set each target accepts. That is the same logic pip and uv use to pick a wheel.
• requirements.txt and bare package names are looked up on the PyPI JSON API. Feed it a fully pinned file (from uv pip compile, pip-compile or uv export): wheelgap checks the lines you give it and doesn't resolve dependencies.
• Environment markers are respected. A pywin32 ; sys_platform == 'win32' dependency won't show up as a Linux gap. For uv.lock the dependency graph is walked per target, so transitive platform-specific packages are handled too.
• --online re-checks lockfile packages against PyPI. Use it when a project has uploaded new wheels for an existing version since you locked, or if your uv.lock was generated with environments restrictions.

Why this exists

Missing wheels show up late, in the most expensive place:

• Your python:3.13-alpine image on an ARM runner takes 25 minutes because two transitive dependencies don't publish musllinux_aarch64 wheels, and QEMU is compiling them.
• A build fails with error: Microsoft Visual C++ 14.0 or greater is required on a teammate's Snapdragon laptop.
• You try free-threaded Python 3.14t and half your stack quietly falls back to source builds, because abi3 wheels don't apply there.

Sites like pyreadiness.org and free-threaded wheels track the top few hundred packages. wheelgap checks your packages, at your pinned versions, for your targets, in about a second, and it can run in CI.

Roadmap

• Pyodide/WebAssembly, iOS and Android targets
• Read targets from [tool.wheelgap] in pyproject.toml
• Private indexes (--index-url, the simple API)
• Infer the target from a Dockerfile (FROM python:3.13-alpine, --platform=linux/arm64)
• "Closest version with a wheel" hints (e.g. upgrade foo 1.2 → 1.4 to get musllinux wheels)

Contributions welcome. Issues labelled good first issue are a good start, and CONTRIBUTING.md has the 3-command dev setup.

License

MIT