---
id: wheel-stub
version: "0.5.0"
license: Apache-2.0
license_treatment: permissive
maintenance: aging
---

# wheel-stub — wheel stub package build backend

License: permissive · Maintenance: aging · Downloads: 1.8M/mo

## What it is and what it does

wheel-stub is a PEP 517 build backend that solves the problem of distributing wheels hosted on non-PyPI indexes while preserving the standard `pip install` user experience. Instead of requiring users to specify custom index URLs or download wheels manually, you configure wheel-stub in your pyproject.toml with a third-party index URL, and it generates a stub package on PyPI that redirects pip to fetch the actual wheel from that index.

The backend has no runtime dependencies and supports Python 3.8 through 3.13 on CPython and PyPy. It vendors its own copies of packaging and tomli to avoid external dependencies. Configuration is minimal: you specify the index URL and optionally control whether to error if the wheel cannot be found, or whether to include CUDA debuginfo in error messages.

Use it for:

- Distribute specialized wheels from a third-party index without requiring users to configure custom pip settings.
- Create a PyPI presence for packages that must remain on a non-PyPI index due to licensing or dependency constraints.
- Simplify installation UX for end users who should not need to know about alternative package indexes.
- Bridge a third-party index and PyPI for packages that cannot be directly mirrored to PyPI.
- Host wheels on a dedicated index while letting users install via standard `pip install` commands.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A PEP 517 build backend that creates stub packages on PyPI pointing to wheels hosted on third-party package indexes, letting users install them with standard `pip install` commands.

Yes, if you need to host wheels on a non-PyPI index and want users to install them with standard pip commands. The package is low-friction to install and has no runtime dependencies. However, maintenance is aging (189 days since last release), so verify it still works with your Python version and index before adopting in production. No known security vulnerabilities.

## Install

pip install wheel-stub
uv add wheel-stub
poetry add wheel-stub

## Installing wheel-stub

Before you install: Low friction: pure Python wheel with no runtime dependencies. Maintenance status is aging (189 days since last release), though the package is classified as Beta and supports current Python versions.

License in practice: Apache-2.0 permissive license. The package vendors packaging (BSD 2-clause and Apache 2 dual licensed) and tomli (MIT licensed), all compatible with permissive use.

Quickstart:

# In pyproject.toml, configure wheel-stub as build backend:
[build-system]
requires = ["wheel-stub"]
build-backend = "wheel_stub"

[tool.wheel-stub]
index_url = "https://pypi.example.com"

# Then build: python -m build --sdist

Requires a third-party package index URL configured in pyproject.toml; the wheel files must already exist on that index.

Verify before relying:

- Whether the package is actively maintained or in maintenance mode (aging status, no recent commits visible).
- Real-world adoption and stability beyond the top-5000 download tier.
- Compatibility with specific third-party indexes and whether stub-only mode behavior is production-ready.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 1.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

PEP 517 build backend, third-party package index redirect, PyPI stub package, wheel hosting redirect, non-PyPI wheel installation, package index soft link, custom index wheel proxy, pep-517, package-distribution, build-backend

[View on SkillFed](https://skillfed.io/packages/wheel-stub) · [View on PyPI](https://pypi.org/project/wheel-stub/)