{"id":4850,"library":"wheel-stub","title":"wheel-stub: External Wheel Hosting Backend","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/wheelnext/wheel-stub","tags":["packaging","build-backend","PEP 517","wheel","PyPI","external index"],"install":[{"cmd":"pip install wheel-stub","lang":"bash","label":"Install wheel-stub"}],"dependencies":[],"imports":[{"note":"wheel-stub operates as a build system component, not a runtime library.","symbol":"wheel-stub build backend","correct":"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."}],"quickstart":{"code":"import os\nimport subprocess\nimport textwrap\nimport shutil\n\n# Create a dummy project directory\nproject_dir = 'my_stub_package'\nif os.path.exists(project_dir):\n    shutil.rmtree(project_dir)\nos.makedirs(project_dir)\nos.chdir(project_dir)\n\n# Create a minimal pyproject.toml to configure wheel-stub\npyproject_content = textwrap.dedent('''\n    [build-system]\n    requires = [\"hatchling\", \"wheel-stub\"]\n    build-backend = \"wheel_stub\"\n\n    [project]\n    name = \"my-stub-package\"\n    version = \"0.1.0\"\n    description = \"A package using wheel-stub\"\n    requires-python = \">=3.8\"\n\n    [tool.wheel_stub]\n    index_url = \"https://pypi.nvidia.com\"\n    source_wheel = \"nvidia_cuda_runtime_cu12-12.4.99-py3-none-manylinux2014_x86_64.whl\"\n''')\n\nwith open('pyproject.toml', 'w') as f:\n    f.write(pyproject_content)\n\n# Create a dummy src directory and __init__.py (required by most build systems)\nos.makedirs('src/my_stub_package')\nwith open('src/my_stub_package/__init__.py', 'w') as f:\n    f.write('__version__ = \"0.1.0\"')\n\nprint(f\"Created project structure in {os.getcwd()}\")\nprint(\"Attempting to build sdist using python -m build...\")\n\n# Attempt to build the sdist using python -m build\ntry:\n    # Using --sdist to trigger the wheel-stub backend as it generates an sdist that links to the remote wheel.\n    # The actual remote wheel should be available at the specified index_url and source_wheel name.\n    # For this quickstart, we are simulating the build step, not a full install with a remote wheel.\n    subprocess.run(['python', '-m', 'build', '--sdist'], check=True)\n    print(\"Successfully invoked wheel-stub backend to create sdist.\")\n    print(\"Check the 'dist/' directory for the generated sdist.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error during build: {e}\")\n    print(\"Ensure 'hatchling' and 'build' are installed: pip install hatchling build\")\n\n# Clean up (optional for quickstart, but good for testing environment)\nos.chdir('..')\n# shutil.rmtree(project_dir)\n","lang":"python","description":"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."},"warnings":[{"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\"`.","message":"The `index_url` configuration option under `[tool.wheel_stub]` in `pyproject.toml` is mandatory. Omitting it will result in a build failure.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}