huggingface/transformers · error · RuntimeError

register_kernel_mapping_transformers requires `kernels` to b

Error message

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

What it means

`register_kernel_mapping_transformers` pre-registers transformers' own layer-to-kernel mappings; like the other symbols in the fallback block it is a stub raising RuntimeError when `kernels` is absent. The failure is a dependency problem, not a logic problem in your mapping.

Source

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

        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."""
    return (
        attn_implementation is not None
        and re.search(r"^[^/:]+/[^/:]+(?:@[^/:]+)?(?::[^/:]+)?$", attn_implementation) is not None

View on GitHub (pinned to a597f97485)

Solutions

  1. Install `kernels` (pin within the compatible range shown in companion error messages).
  2. Call it only when `is_kernels_available()` returns True.
  3. Verify with `python -c "import kernels"` to distinguish not-installed from wrong-version.

Example fix

# before
register_kernel_mapping_transformers()  # RuntimeError

# after
from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    register_kernel_mapping_transformers()
Defensive patterns

Strategy: validation

Validate before calling

from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    register_kernel_mapping_transformers()

Try / catch

try:
    register_kernel_mapping_transformers()
except RuntimeError as e:
    if "kernels" in str(e):
        pass  # run without pre-registered transformers kernel mappings
    else:
        raise

Prevention

When it happens

Trigger: Calling `register_kernel_mapping_transformers()` during model/kernel initialization in an environment without `kernels`.

Common situations: Startup code that eagerly registers all transformers kernel mappings; environments where transformers was installed without the optional kernels extra but the application unconditionally initializes kernel support.

Related errors

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