Registry / devops / wheel-stub

wheel-stub

JSON →
library0.5.0pypypi✓ verified 23d ago

wheel-stub is a PEP 517 build backend designed to act as a "soft link" between a package released on a third-party package index and pypi.org. It enables users to maintain the straightforward `pip install foo` experience while the actual wheel files are hosted on a non-PyPI index. The current version is 0.5.0, released on February 6, 2026, and typically follows a needs-based release cadence.

pip install wheel-stub
INSTALL
IMPORT
SIG · WHEEL-STUB
W
wheel-stub
devopspythonv0.5.0
Install
1.6s avg
Import
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

wheel-stub build backend
This library is a PEP 517 build backend and is not typically imported directly in application code. It is invoked by build frontends like 'hatch' or 'python -m build' based on the 'build-backend' entry in pyproject.toml.
wheel-stub operates as a build system component, not a runtime library.

This quickstart demonstrates how to set up a minimal Python project to utilize `wheel-stub` as its build backend. It creates a `pyproject.toml` file with the necessary `[build-system]` and `[tool.wheel_stub]` configurations, including a required `index_url` and `source_wheel`. It then invokes `python -m build --sdist` to trigger `wheel-stub`, which generates a source distribution that acts as a 'soft link' to an externally hosted wheel. Note that `hatchling` is used here as a common build requirement, and the example `index_url` and `source_wheel` point to NVIDIA's PyPI for demonstration purposes; a real-world scenario would use your specific third-party index and wheel.

import os import subprocess import textwrap import shutil # Create a dummy project directory project_dir = 'my_stub_package' if os.path.exists(project_dir): shutil.rmtree(project_dir) os.makedirs(project_dir) os.chdir(project_dir) # Create a minimal pyproject.toml to configure wheel-stub pyproject_content = textwrap.dedent(''' [build-system] requires = ["hatchling", "wheel-stub"] build-backend = "wheel_stub" [project] name = "my-stub-package" version = "0.1.0" description = "A package using wheel-stub" requires-python = ">=3.8" [tool.wheel_stub] index_url = "https://pypi.nvidia.com" source_wheel = "nvidia_cuda_runtime_cu12-12.4.99-py3-none-manylinux2014_x86_64.whl" ''') with open('pyproject.toml', 'w') as f: f.write(pyproject_content) # Create a dummy src directory and __init__.py (required by most build systems) os.makedirs('src/my_stub_package') with open('src/my_stub_package/__init__.py', 'w') as f: f.write('__version__ = "0.1.0"') print(f"Created project structure in {os.getcwd()}") print("Attempting to build sdist using python -m build...") # Attempt to build the sdist using python -m build try: # Using --sdist to trigger the wheel-stub backend as it generates an sdist that links to the remote wheel. # The actual remote wheel should be available at the specified index_url and source_wheel name. # For this quickstart, we are simulating the build step, not a full install with a remote wheel. subprocess.run(['python', '-m', 'build', '--sdist'], check=True) print("Successfully invoked wheel-stub backend to create sdist.") print("Check the 'dist/' directory for the generated sdist.") except subprocess.CalledProcessError as e: print(f"Error during build: {e}") print("Ensure 'hatchling' and 'build' are installed: pip install hatchling build") # Clean up (optional for quickstart, but good for testing environment) os.chdir('..') # shutil.rmtree(project_dir)
Debug
Known issues
breakingThe `index_url` configuration option under `[tool.wheel_stub]` in `pyproject.toml` is mandatory. Omitting it will result in a build failure.
fix
Always specify a valid `index_url` pointing to your third-party package index in your `pyproject.toml` file, e.g., `index_url = "https://your.private.repo/simple"`.
affects: All versions
gotchaSetting `stub_only = true` in your `pyproject.toml` will prevent `wheel-stub` from installing the actual wheel from the third-party repository. Instead, it will error with instructions on how to use the repository directly.
fix
If you intend for the actual wheel to be installed via the stub, ensure `stub_only` is either `false` or omitted (as `false` is the default). Use `stub_only = true` only when explicit redirection to the third-party index is desired.
affects: All versions
gotchawheel-stub currently functions as a workaround for external wheel hosting limitations. PEP 759, which aimed to standardize external wheel hosting, was withdrawn. This means while `wheel-stub` is functional, future official Python packaging standards might supersede or alter its role, potentially requiring migration.
fix
Projects relying on `wheel-stub` should monitor Python packaging developments for official solutions to external wheel hosting. Be prepared for potential migration if more standardized and integrated mechanisms emerge.
affects: All versions
Upgrade
Version history
0.5.0latest on PyPI · released Feb 6, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
Resources
wheel-stub — pip install wheel-stub · libregistry