wheel-stub: External Wheel Hosting Backend

0.5.0 · active · verified Sun Apr 12

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.

Warnings

breaking The `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"`.
gotcha Setting `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.
gotcha wheel-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.

Install

pip install wheel-stub Install wheel-stub

Imports

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.

Quickstart

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)

view raw JSON →