headroomlabs-ai/headroom · error · ImportError

Magika is required for ML-based content detection. Install w

Error message

Magika is required for ML-based content detection. Install with: pip install magika

What it means

Raised from the lazy Magika singleton loader in headroom.compression.detector when `from magika import Magika` raises ImportError. Magika is the ML-based content-type detector used to classify file contents; it is an optional dependency, so it is only imported on first use and the failure surfaces as an ImportError with install instructions chained from the original error. A companion _magika_available() helper exists so callers can probe availability without triggering the load.

Source

Thrown at headroom/compression/detector.py:141

        "org",
    }
)


def _get_magika() -> Magika:
    """Get or create the singleton Magika instance.

    Lazy-loads on first use to avoid import cost if not needed.
    """
    global _magika_instance
    if _magika_instance is None:
        try:
            from magika import Magika

            _magika_instance = Magika()
            logger.debug("Magika model loaded successfully")
        except ImportError as e:
            raise ImportError(
                "Magika is required for ML-based content detection. "
                "Install with: pip install magika"
            ) from e
    return _magika_instance


def _magika_available() -> bool:
    """Check if Magika is available without loading it."""
    try:
        import magika  # noqa: F401

        return True
    except ImportError:
        return False


class MagikaDetector:
    """ML-based content type detector using Google's Magika.

View on GitHub (pinned to 322425c43b)

Solutions

Install magika into the same interpreter headroom uses: `pip install magika`
If it should already be installed, check `python -c "import magika"` in that exact environment and fix the interpreter/venv mismatch
If ML detection is optional for your flow, gate the feature with headroom's `_magika_available()` probe (or a try/except around the detector call) instead of letting the ImportError propagate

Example fix

# before
from headroom.compression.detector import _get_magika
magika = _get_magika()  # ImportError: Magika is required...

# after
# pip install magika
from headroom.compression.detector import _get_magika
magika = _get_magika()  # loads model on first call

Defensive patterns

Strategy: try-catch

Validate before calling

from headroom.compression.detector import _magika_available

if not _magika_available():
    print("magika not installed — ML content detection disabled; `pip install magika` to enable")

Try / catch

try:
    from headroom.compression.detector import _get_magika
    magika = _get_magika()
except ImportError as e:
    logger.warning("ML detection unavailable (%s); falling back to heuristic detection", e)
    magika = None

Prevention

Declare magika in your deployment environment when ML detection is required
Use _magika_available() to feature-probe instead of catching the load-time ImportError
Run import smoke-tests (`python -c 'import magika'`) in CI for the exact interpreter

When it happens

Trigger: Any code path that first requests the Magika singleton (content detection on compression candidate files) in an environment where the `magika` package is not installed, is installed in a different interpreter, or fails to import (e.g. missing model assets on old magika versions).

Common situations: headroom installed without the optional ML extra; running under a different Python than the one where magika was pip-installed; slim Docker images that trimmed optional deps; air-gapped environments where magika's model download at Magika() construction was blocked (note: that would raise a different error, but import-time failures land here too).

Related errors

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