{"record":{"id":"08160797b24ee161","repo":"headroomlabs-ai/headroom","slug":"kompress-requires-onnxruntime-or-torch-install-wi","errorCode":null,"errorMessage":"Kompress requires onnxruntime or torch. Install with: pip install headroom-ai[proxy]","messagePattern":"Kompress requires onnxruntime or torch\\. Install with: pip install headroom-ai\\[proxy\\]","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/transforms/kompress_compressor.py","lineNumber":1005,"sourceCode":"\n    # Auto mode: preserve stable default behavior. This avoids changing\n    # compression quality/perf characteristics for existing installs while\n    # allowing opt-in MPS/CoreML experiments via HEADROOM_KOMPRESS_BACKEND.\n    if _is_onnx_available():\n        try:\n            return _load_kompress_onnx(model_id, use_coreml=False, allow_download=allow_download)\n        except KompressModelNotCached:\n            # Cache-only miss: don't trigger a PyTorch network download as a\n            # fallback — propagate so the caller can defer.\n            if not allow_download:\n                raise\n        except Exception as e:\n            logger.warning(\"ONNX load failed for %s, trying PyTorch: %s\", model_id, e)\n\n    if _is_pytorch_available():\n        return _load_kompress_pytorch(model_id, device, allow_download=allow_download)\n\n    raise ImportError(\n        \"Kompress requires onnxruntime or torch. Install with: pip install headroom-ai[proxy]\"\n    )\n\n\ndef unload_kompress_model(model_id: str | None = None) -> bool:\n    \"\"\"Unload Kompress model(s) to free memory.\n\n    Args:\n        model_id: Specific model to unload. If None, unloads all cached models.\n    \"\"\"\n    with _kompress_lock:\n        if model_id is not None:\n            if model_id in _kompress_cache:\n                del _kompress_cache[model_id]\n            else:\n                return False\n        elif _kompress_cache:\n            _kompress_cache.clear()","sourceCodeStart":987,"sourceCodeEnd":1023,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/kompress_compressor.py#L987-L1023","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nload_kompress_model(model_id)  # ImportError: requires onnxruntime or torch\n\n# after\ntry:\n    load_kompress_model(model_id)\nexcept ImportError:\n    use_builtin_compressors()  # or shell: pip install headroom-ai[proxy]","handlingStrategy":"try-catch","validationCode":"def kompress_runtime_available() -> bool:\n    try:\n        import onnxruntime  # noqa: F401\n        return True\n    except ImportError:\n        pass\n    try:\n        import torch  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not kompress_runtime_available():\n    disable_kompress()","typeGuard":"def kompress_backend() -> str | None:\n    try:\n        import onnxruntime  # noqa: F401\n        return \"onnx\"\n    except ImportError:\n        pass\n    try:\n        import torch  # noqa: F401\n        return \"torch\"\n    except ImportError:\n        return None","tryCatchPattern":"try:\n    load_kompress_model(model_id)\nexcept ImportError as e:\n    if \"Kompress requires\" in str(e):\n        use_builtin_compressors()\n    else:\n        raise","preventionTips":["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."],"tags":["dependency","import-error","onnx","pytorch","installation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}