headroomlabs-ai/headroom · error · ImportError

tree-sitter is not installed. Install with: pip install head

Error message

tree-sitter is not installed. Install with: pip install headroom-ai[code]\nThis adds ~50MB for tree-sitter grammars.

What it means

Raised by _get_parser when _tree_sitter_importable() returns False, i.e. the optional tree-sitter dependency (plus its grammar wheels) is not installed in the current environment. Headroom keeps tree-sitter behind the headroom-ai[code] extra because the grammars add ~50MB, so the import is lazy and this ImportError is the explicit failure when the extra is missing.

Source

Thrown at headroom/transforms/code_compressor.py:142

    contract with negligible extra memory.

    Args:
        language: Language name (e.g., 'python', 'javascript').

    Returns:
        Configured ``tree_sitter.Parser`` bound to the current thread.

    Raises:
        ImportError: If tree-sitter is not installed.
        ValueError: If language is not supported.
    """
    if language in _UNSAFE_TREE_SITTER_LANGUAGES:
        raise ValueError(f"Language '{language}' is quarantined for code-aware compression.")
    # NOTE: guard on importability (not _check_tree_sitter_available), because
    # _check_tree_sitter_available now performs a real end-to-end parse via
    # _get_parser; guarding on it here would recurse.
    if not _tree_sitter_importable():
        raise ImportError(
            "tree-sitter is not installed. Install with: pip install headroom-ai[code]\n"
            "This adds ~50MB for tree-sitter grammars."
        )

    parsers: dict[str, Any] | None = getattr(_tree_sitter_local, "parsers", None)
    if parsers is None:
        parsers = {}
        _tree_sitter_local.parsers = parsers

    if language not in parsers:
        try:
            from tree_sitter import Parser
            from tree_sitter_language_pack import get_language

            parser = Parser()
            # `language` is a validated runtime str; get_language types its arg
            # as a Literal of supported names, which a dynamic str can't satisfy.
            parser.language = get_language(language)  # type: ignore[arg-type]

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install headroom-ai[code] (or pip install "headroom-ai[code]@your-version") to add tree-sitter and its grammars.
2. Verify with: python -c "import tree_sitter, tree_sitter_language_pack" before enabling code-aware compression.
3. If the ~50MB is unacceptable, disable code-aware compression so the parser path is never entered.

Example fix

# before: ImportError from _get_parser
session.compress(code, mode="code_aware")

# after
try:
    from headroom.transforms.code_compressor import is_tree_sitter_available  # guarded probe
except ImportError:
    pass
# shell: pip install headroom-ai[code]

from headroom.transforms.code_compressor import is_tree_sitter_available
if not is_tree_sitter_available():
    disable_code_aware_compression()

def treesitter_ready() -> bool:
    try:
        import tree_sitter  # noqa: F401
        import tree_sitter_language_pack  # noqa: F401
        return True
    except ImportError:
        return False

try:
    parser = _get_parser(language)
except ImportError as e:
    if "tree-sitter is not installed" in str(e):
        logger.error("Install headroom-ai[code] to enable code-aware compression")
        raise
    raise

When it happens

Trigger: Calling _get_parser(any_language) — or any higher-level code-aware compression API that reaches it — in an environment where 'pip install headroom-ai[code]' (tree-sitter + language packs) was never run, or the venv changed.

Common situations: Installing only the base headroom-ai package and then enabling code-aware compression; a CI image or slim Docker container that strips optional deps; upgrading headroom into a fresh virtualenv without re-adding extras.

Related errors

• Kompress requires onnxruntime or torch. Install with: pip in
• LangChain is required for this integration. Install with: pi
• tiktoken is required for OpenAI provider. Install with: pip
• ccr sqlite backend init failed: {0}
• failed to download `{repo}` from HuggingFace Hub: {source}

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