huggingface/transformers · error · RuntimeError

FuncRepository requires `kernels` to be installed. Run `pip

Error message

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

What it means

`FuncRepository` wraps a plain kernel function (as opposed to a Hub layer) and, in the no-`kernels` fallback block, is replaced by a stub whose constructor raises RuntimeError. The message makes explicit that the entire hub-kernels integration is unavailable without the optional `kernels` dependency.

Source

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

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

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

    class LocalLayerRepository:
        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},

View on GitHub (pinned to a597f97485)

Solutions

`pip install kernels` (compatible version range per the error text).
Skip function-kernel wrapping when `is_kernels_available()` is False.
Load the model with `attn_implementation="eager"`/default and no kernel config to avoid the path entirely.

Example fix

# before
repo = FuncRepository(my_kernel_func)  # RuntimeError

# after
from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    repo = FuncRepository(my_kernel_func)
else:
    repo = None

Defensive patterns

Strategy: type-guard

Validate before calling

from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    from transformers.integrations.hub_kernels import FuncRepository
    repo = FuncRepository(func)
else:
    repo = None

Type guard

def func_repository_usable() -> bool:
    from transformers.utils.import_utils import is_kernels_available
    return is_kernels_available()

Try / catch

try:
    repo = FuncRepository(func)
except RuntimeError as e:
    if "kernels" in str(e):
        repo = None
    else:
        raise

Prevention

Declare `kernels` in your project dependencies if any code path touches FuncRepository.
Feature-detect once at startup and branch, rather than catching at every call site.

When it happens

Trigger: Instantiating `FuncRepository(...)` — directly or through kernelized model code paths that wrap hub functions — without `kernels` installed.

Common situations: Loading a kernelized model (e.g. with `kernelize`/`use_kernel_func_from_hub`) on a machine where only core transformers is installed.

Related errors

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