Reference

Flags

wheelripe [PATH|SPEC ...] [options]
wheelripe wheel FILE.whl ... [-p PY] [--platform KEY]
wheelripe mcp

Flag	Default	Meaning
`-p, --python`	3.15	Target CPython; `t` = free-threaded.
`--platform KEY`	linux-x86_64, macos-arm64, windows-amd64	Repeat or comma-separate.
`--all-platforms`		Every known key.
`--glibc / --musl / --macos`	2.34 / 1.2 / 14	Oldest system you deploy on.
`-f, --format`	text	`text`, `json`, `markdown`, `github`.
`--fail-on`	bump	`bump`, `blocked`, `build`, `never`.
`--show-ready`		List ready packages one by one.
`--pre`		Allow pre-releases as the suggested bump.
`-i, --index-url URL`	PyPI	Simple-API index (PEP 691/503) to use instead of PyPI. Credentials in the URL are never printed.
`--extra-index-url URL`		One more simple-API index; repeatable; files are pooled.
`--index URL`	https://pypi.org/pypi	PyPI JSON API base, for a mirror of it.
`--workers N`	8	Parallel index requests.
`-o, --output FILE`	stdout	Write the report to a file.
`--summary FILE`		Append a Markdown summary (e.g. `$GITHUB_STEP_SUMMARY`).
`--json-out FILE`		Also write the JSON report.
`--annotations`		Also print `::error`/`::warning` lines.
`-V, --version`		Print the version.

Exit codes

Code	Meaning
0	Nothing at or above the `--fail-on` level.
1	Something is; the report says what.
2	Usage error, unreadable input, an index that could not be reached, or one that answered with something that is not a simple index page.

Statuses

Status	Meaning
`ready`	A wheel for this version installs on the target.
`skip`	An environment marker excludes the package on this target.
`build`	The release has only an sdist (for every Python).
`bump`	No wheel at this version; `fix` names the first newer release with one.
`blocked`	No release has a wheel for the target yet.
`excluded`	The release's `requires-python` excludes the target.
`missing`	The package or version is not on the index.

A package's overall status is its worst status across the platforms you asked for.

Yanked files (PEP 592) are skipped, as pip skips them — except when an exact pin selects a yanked release: pip installs it then, with a warning, so wheelripe judges that release and marks the package "yanked": true.

Platform keys

Key	Wheel tags accepted
`linux-x86_64`, `linux-aarch64`	`manylinux_X_Y_ARCH` with X.Y ≤ glibc floor, legacy `manylinux1/2010/2014`, `linux_ARCH`
`musllinux-x86_64`, `musllinux-aarch64`	`musllinux_X_Y_ARCH` with X.Y ≤ musl floor
`macos-arm64`	`macosx_X_Y_arm64` / `universal2`, X ≤ macOS floor
`macos-x86_64`	`x86_64`, `intel`, `universal`, `universal2` …
`windows-amd64`, `windows-arm64`, `windows-x86`	`win_amd64`, `win_arm64`, `win32`

Interpreter and ABI rules

Wheel	3.15 (GIL)	3.15t (free-threaded)
`cp315-cp315`	yes	no
`cp315-cp315t`	no	yes
`cp3X-abi3`, X ≤ 15	yes	no
`cp3X-abi3t`, 14 ≤ X ≤ 15 (PEP 803)	no	yes
`cp3X-abi3.abi3t`	yes	yes
`py3-none-any`	yes	yes

JSON report

{
  "tool": "wheelripe",
  "python": "3.15",
  "platforms": ["linux-x86_64", "macos-arm64", "windows-amd64"],
  "sources": ["uv.lock"],
  "ripe": false,
  "summary": {"ready": 1, "skip": 0, "build": 0, "bump": 2,
              "blocked": 1, "excluded": 0, "missing": 0},
  "packages": [
    {
      "name": "numpy", "version": "1.26.4", "pinned": true,
      "status": "bump", "fix": "2.5.2",
      "platforms": {"linux-x86_64": {"status": "bump", "note": "..."}},
      "latest": "2.5.4", "ships": ["cp39", "cp310", "cp311", "cp312"],
      "requires_python": ">=3.9",
      "upstream": "https://github.com/numpy/numpy",
      "origin": "uv.lock"
    }
  ]
}

Packages are sorted worst first. Fields that do not apply are omitted. Two top-level fields appear only when they have something to say: indexes (the indexes consulted, redacted, when anything besides PyPI was used, e.g. ["download.pytorch.org/whl/cpu", "pypi.org"]) and warnings (index problems such as a 401, also printed to stderr).

FAQ →