headroomlabs-ai/headroom · error · ImportError

Kompress requires onnxruntime or torch. Install with: pip in

Error message

Kompress requires onnxruntime or torch. Install with: pip install headroom-ai[proxy]

What it means

Terminal ImportError from the top-level Kompress loader: the ONNX backend is unavailable (or its load failed in a way that fell through) and _is_pytorch_available() is False, so neither onnxruntime nor torch exists to run the neural compressor. Kompress is an optional heavy dependency, so the error directs you to the headroom-ai[proxy] extra that bundles a runtime.

Source

Thrown at headroom/transforms/kompress_compressor.py:1005

    # Auto mode: preserve stable default behavior. This avoids changing
    # compression quality/perf characteristics for existing installs while
    # allowing opt-in MPS/CoreML experiments via HEADROOM_KOMPRESS_BACKEND.
    if _is_onnx_available():
        try:
            return _load_kompress_onnx(model_id, use_coreml=False, allow_download=allow_download)
        except KompressModelNotCached:
            # Cache-only miss: don't trigger a PyTorch network download as a
            # fallback — propagate so the caller can defer.
            if not allow_download:
                raise
        except Exception as e:
            logger.warning("ONNX load failed for %s, trying PyTorch: %s", model_id, e)

    if _is_pytorch_available():
        return _load_kompress_pytorch(model_id, device, allow_download=allow_download)

    raise ImportError(
        "Kompress requires onnxruntime or torch. Install with: pip install headroom-ai[proxy]"
    )


def unload_kompress_model(model_id: str | None = None) -> bool:
    """Unload Kompress model(s) to free memory.

    Args:
        model_id: Specific model to unload. If None, unloads all cached models.
    """
    with _kompress_lock:
        if model_id is not None:
            if model_id in _kompress_cache:
                del _kompress_cache[model_id]
            else:
                return False
        elif _kompress_cache:
            _kompress_cache.clear()

View on GitHub (pinned to 322425c43b)

Solutions

pip install headroom-ai[proxy] to get onnxruntime (and/or torch).
If size matters, install just onnxruntime (pip install onnxruntime) — it is the lighter backend the loader prefers first.
If Kompress is optional for you, gate it: probe availability and fall back to the non-neural compressors when absent.

Example fix

# before
load_kompress_model(model_id)  # ImportError: requires onnxruntime or torch

# after
try:
    load_kompress_model(model_id)
except ImportError:
    use_builtin_compressors()  # or shell: pip install headroom-ai[proxy]

Defensive patterns

Strategy: try-catch

Validate before calling

def kompress_runtime_available() -> bool:
    try:
        import onnxruntime  # noqa: F401
        return True
    except ImportError:
        pass
    try:
        import torch  # noqa: F401
        return True
    except ImportError:
        return False

if not kompress_runtime_available():
    disable_kompress()

Type guard

def kompress_backend() -> str | None:
    try:
        import onnxruntime  # noqa: F401
        return "onnx"
    except ImportError:
        pass
    try:
        import torch  # noqa: F401
        return "torch"
    except ImportError:
        return None

Try / catch

try:
    load_kompress_model(model_id)
except ImportError as e:
    if "Kompress requires" in str(e):
        use_builtin_compressors()
    else:
        raise

Prevention

Install headroom-ai[proxy] wherever neural compression is enabled.
Probe for onnxruntime/torch at startup and degrade gracefully.
onnxruntime alone is the lighter path; add torch only if you need the PyTorch backend.

When it happens

Trigger: Loading the Kompress model in an environment with neither onnxruntime nor torch installed — typically base-package installs where the [proxy] extra was skipped, or a slim image that strips both ML runtimes.

Common situations: pip install headroom-ai without extras followed by enabling neural compression; a Docker image built for the text-only path; CI matrices that omit the heavy deps and still run Kompress tests.

Related errors

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