# wheelgap

> wheelgap is a Python command-line tool that reads a lockfile (`uv.lock`, `pylock.toml`, `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `requirements.txt`) or package names and reports, for each package and each target Python and platform (Linux x86_64 and ARM, Alpine/musl, macOS, Windows on ARM, free-threaded 3.14t, Pyodide, iOS, Android), whether pip or uv would install a prebuilt wheel, build from source, or fail. Run the newest release with `uvx wheelgap@latest` (plain `uvx wheelgap` can reuse an older installed or cached version), always pass `-p` and `-t`, and read `--json` and the exit code: `0` no gaps, `1` gaps found (including packages that couldn't be looked up), `2` bad input.

The README and docs on `main` can describe changes that aren't on PyPI yet; `CHANGELOG.md` lists them under "Unreleased". Check `uvx wheelgap@latest --help` for the flags the released version has.

## Docs

- [Using wheelgap from an agent or script](https://github.com/wheelgap/wheelgap/blob/main/docs/recipes.md#using-wheelgap-from-an-agent-or-script): `uvx`, exit codes, reading `--json`, `--explain`, accepting gaps, with a worked example
- [Install and run](https://github.com/wheelgap/wheelgap#install-and-run-under-30-seconds): `uvx wheelgap`, `pipx run wheelgap` or `pip install wheelgap`
- [Usage](https://github.com/wheelgap/wheelgap#usage): examples, `[tool.wheelgap]` config, result statuses, `--explain`, how `--json` results are keyed, exit codes, `--ignore`
- [Targets](https://github.com/wheelgap/wheelgap#targets): platform names and aliases, the wheel tags each accepts, `--glibc`, `--musl`, `--distro`
- [Comparing two lockfiles](https://github.com/wheelgap/wheelgap#comparing-two-lockfiles): `wheelgap diff OLD NEW`, git refs such as `origin/main:uv.lock`, `--json`
- [How it works](https://github.com/wheelgap/wheelgap#how-it-works): what is read offline, what is looked up on PyPI, environment markers
- [Recipes](https://github.com/wheelgap/wheelgap/blob/main/docs/recipes.md): multi-arch images, free-threading readiness, monorepos, agents and scripts
- [JSON schema](https://github.com/wheelgap/wheelgap/blob/main/docs/wheelgap-output.schema.json): the shape of `--json` output on `main`; later versions may add keys

## Integrations

- [In CI (GitHub Action)](https://github.com/wheelgap/wheelgap#in-ci-github-action): the Action, `--markdown` for job summaries
- [With pre-commit](https://github.com/wheelgap/wheelgap#with-pre-commit): the pre-commit hook
- [From Python](https://github.com/wheelgap/wheelgap#from-python): `make_targets`, `check_package`, `check_lockfile`
- [With an AI coding agent](https://github.com/wheelgap/wheelgap#with-an-ai-coding-agent): the `check-wheels` skill for Claude Code, Codex, Cursor and Copilot

## Optional

- [AGENTS.md](https://github.com/wheelgap/wheelgap/blob/main/AGENTS.md): instructions for coding agents contributing to wheelgap itself
- [CHANGELOG.md](https://github.com/wheelgap/wheelgap/blob/main/CHANGELOG.md): released versions, and changes not yet on PyPI under "Unreleased"
