huggingface/transformers · error · RuntimeError

register_kernel_mapping requires `kernels` to be installed.

Error message

register_kernel_mapping requires `kernels` to be installed. Run `pip install kernels`.

What it means

`register_kernel_mapping` installs a mapping from layer names to Hub kernel repos for the current process. Without the `kernels` package it is a stub that raises RuntimeError on any call, informing you the hub-kernel subsystem is inactive and how to enable it.

Source

Thrown at src/transformers/integrations/hub_kernels.py:571

        def __init__(self, *args, **kwargs):
            raise RuntimeError("LocalLayerRepository requires `kernels` to be installed. Run `pip install kernels`.")

        def load(self):
            raise NotImplementedError(
                "LocalLayerRepository requires `kernels` to be installed. Run `pip install kernels."
            )

    class FuncRepository:
        def __init__(self, *args, **kwargs):
            raise RuntimeError("FuncRepository requires `kernels` to be installed. Run `pip install kernels`.")

    def replace_kernel_forward_from_hub(*args, **kwargs):
        raise RuntimeError(
            "replace_kernel_forward_from_hub requires `kernels` to be installed. Run `pip install kernels`."
        )

    def register_kernel_mapping(*args, **kwargs):
        raise RuntimeError("register_kernel_mapping requires `kernels` to be installed. Run `pip install kernels`.")

    def register_kernel_mapping_transformers(*args, **kwargs):
        raise RuntimeError(
            "register_kernel_mapping_transformers requires `kernels` to be installed. Run `pip install kernels`."
        )


_HUB_KERNEL_MAPPING: dict[str, dict[str, str]] = {
    "finegrained-fp8": {"repo_id": "kernels-community/finegrained-fp8", "version": 4},
    "deep-gemm": {"repo_id": "kernels-community/deep-gemm", "version": 2},
    "sonic-moe": {"repo_id": "kernels-community/sonic-moe", "revision": "ep-support"},
}

_KERNEL_MODULE_MAPPING: dict[str, ModuleType | None] = {}


def is_kernel(attn_implementation: str | None) -> bool:
    """Check whether `attn_implementation` matches a kernel pattern from the hub."""

View on GitHub (pinned to a597f97485)

Solutions

Install `kernels` in a compatible version.
Wrap registration in `if is_kernels_available():`.
Pass kernel mappings via `KernelConfig`/model kwargs only on machines where kernels are set up.

Example fix

# before
register_kernel_mapping({"LlamaDecoderLayer": "kernels-community/llama-layer"})  # RuntimeError

# after
from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    register_kernel_mapping({"LlamaDecoderLayer": "kernels-community/llama-layer"})

Defensive patterns

Strategy: validation

Validate before calling

from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    register_kernel_mapping(mapping)

Try / catch

try:
    register_kernel_mapping(mapping)
except RuntimeError as e:
    if "kernels" in str(e):
        logging.warning("kernels not installed; skipping kernel mapping")
    else:
        raise

Prevention

Centralize kernel setup in one function guarded by is_kernels_available().
Add `kernels` to the environment spec for any deployment using hub kernels.

When it happens

Trigger: Calling `register_kernel_mapping(...)` (common in setup code that wires custom kernels into a model) when `kernels` is not installed.

Common situations: Copy-pasted kernel setup snippets into a project whose environment lacks `kernels`; onboarding scripts that register mappings unconditionally.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/567936329dfca4b5. Report an issue: GitHub.