headroomlabs-ai/headroom · error · PlatformNotSupported

{tool}: distributed via PyPI only; `pip install headroom-ai`

Error message

{tool}: distributed via PyPI only; `pip install headroom-ai` should have placed `{entry.get('binary', tool)}` on PATH.

What it means

_asset_for_platform raises PlatformNotSupported when a tool is distributed via PyPI (registry entry has version 'pypi' or no assets) and therefore has no downloadable platform binary. The expectation is that 'pip install headroom-ai' already placed the entry's binary (entry['binary'], falling back to the tool name) on PATH; a fetch cannot fix its absence.

Source

Thrown at headroom/binaries.py:211

def _tool_entry(tool: str) -> dict[str, Any]:
    reg = _registry()
    tools: dict[str, Any] = reg.get("tools", {})
    if tool not in tools:
        raise KeyError(f"unknown tool {tool!r}; known: {sorted(tools)}")
    entry: dict[str, Any] = tools[tool]
    return entry


def _is_pypi_tool(tool: str) -> bool:
    entry = _tool_entry(tool)
    return entry.get("version") == "pypi" or not entry.get("assets")


def _asset_for_platform(tool: str, plat: PlatformKey) -> dict[str, Any]:
    entry = _tool_entry(tool)
    if _is_pypi_tool(tool):
        raise PlatformNotSupported(
            f"{tool}: distributed via PyPI only; `pip install headroom-ai` "
            f"should have placed `{entry.get('binary', tool)}` on PATH."
        )
    assets: dict[str, Any] = entry.get("assets", {})
    asset: dict[str, Any] | None = assets.get(plat.key())
    if asset is None:
        supported = sorted(assets.keys())
        raise PlatformNotSupported(
            f"{tool}: no prebuilt binary for {plat.key()}; supported: {supported}"
        )
    return asset


def _mirror_url(url: str) -> str:
    mirror = os.environ.get("HEADROOM_BINARIES_MIRROR")
    if not mirror:
        return url
    # Only substitute the github.com host so that paths remain intact.

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the package properly: pip install headroom-ai, which places the console script on PATH.
2. Verify the binary resolves: which <binary-name> (the name is printed in the error message).
3. If using a source checkout, pip install -e . so entry points are generated.
4. Ensure the venv's bin/ (or Scripts\ on Windows) is on PATH.

Example fix

# before
python -c "from headroom.binaries import ensure_binary; ensure_binary('some-pypi-tool')"
# PlatformNotSupported: distributed via PyPI only

# after
pip install headroom-ai
which some-pypi-tool  # resolves now

import shutil

def pypi_tool_on_path(binary: str) -> bool:
    return shutil.which(binary) is not None

if not pypi_tool_on_path("some-tool"):
    raise SystemExit("run `pip install headroom-ai`; its console scripts must be on PATH")

try:
    path = ensure_binary("some-tool")
except PlatformNotSupported as e:
    if "distributed via PyPI only" in str(e):
        raise SystemExit("install headroom-ai into this environment; binary must be on PATH") from e
    raise

When it happens

Trigger: Requesting a platform asset for a PyPI-distributed tool (e.g. a pure-Python console script) while running from a source checkout or an environment where the headroom package's scripts directory is not on PATH.

Common situations: Running from a git checkout without 'pip install -e .', a broken venv whose bin/ directory is not on PATH, or manually invoking the binaries module outside an installed package context.

Related errors

• {tool}: no prebuilt binary for {plat.key()}; supported: {sup
• archive did not contain expected member {member!r}
• offline mode (HEADROOM_BINARIES_OFFLINE=1) but fetch require
• binary cache directory parent is not writable: {dest.parent}
• binary cache directory is not writable: {dest.parent}

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/0bdf689afa825867. Report an issue: GitHub.