huggingface/transformers · error · RuntimeError

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

Error message

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

What it means

When the optional `kernels` package (hub kernels loader) is not installed, `hub_kernels.py` defines a fallback `LayerRepository` stub whose `__init__` immediately raises RuntimeError. This makes missing-dependency failures loud at the point of use instead of silently returning a non-functional object, and tells you the exact pip command to fix it.

Source

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

            return cls

        return decorator

    def use_kernelized_func(*args, **kwargs):
        def decorator(cls):
            return cls

        return decorator

    def use_kernel_func_from_hub(*args, **kwargs):
        def decorator(cls):
            return cls

        return decorator

    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):

View on GitHub (pinned to a597f97485)

Solutions

Install the dependency: `pip install kernels` (pin a compatible version, e.g. `pip install kernels==<KERNELS_MIN_VERSION>`).
Guard kernel-loading code behind `transformers.utils.import_utils.is_kernels_available()`.
If kernels are optional for your flow, skip the `use_kernel_forward_from_hub` decoration path when unavailable.

Example fix

# before
from transformers.integrations.hub_kernels import LayerRepository
repo = LayerRepository("kernels-community/foo")  # RuntimeError

# after
from transformers.utils.import_utils import is_kernels_available
if is_kernels_available():
    from transformers.integrations.hub_kernels import LayerRepository
    repo = LayerRepository("kernels-community/foo")
else:
    repo = None  # skip kernel loading

Defensive patterns

Strategy: type-guard

Validate before calling

from transformers.utils.import_utils import is_kernels_available
assert is_kernels_available(), "pip install kernels",
repo = LayerRepository("kernels-community/foo")

Type guard

from transformers.utils.import_utils import is_kernels_available

def kernels_available() -> bool:
    return is_kernels_available()

Try / catch

try:
    repo = LayerRepository(repo_id)
except RuntimeError as e:
    if "kernels" in str(e):
        repo = None  # degrade to non-kernel path
    else:
        raise

Prevention

Install the kernels extra in any environment that loads hub kernels.
Gate all hub_kernels imports behind is_kernels_available().
Pin kernels to the version range supported by your transformers version.

When it happens

Trigger: Importing or instantiating `LayerRepository(...)` from `transformers.integrations.hub_kernels` (or via `use_kernel_forward_from_hub` code paths that construct it) in an environment where `import kernels` fails.

Common situations: Running a kernel-enabled example (e.g. FLA/mamba hub kernels) in a slim install of transformers without the `[kernel]` extra; CI images that strip optional dependencies; code copied from a setup that had `kernels` installed.

Related errors

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