huggingface/transformers · error · RuntimeError

LocalLayerRepository requires `kernels` to be installed. Run

Error message

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

What it means

`LocalLayerRepository` is the stub replacement for the `kernels` package's class that loads kernels from a local directory instead of the Hub. In environments without `kernels`, its `__init__` raises RuntimeError immediately with the install instruction, mirroring the `LayerRepository` stub.

Source

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

        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):
        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`.")

View on GitHub (pinned to a597f97485)

Solutions

1. Install `kernels` (`pip install kernels`) even for local kernel use — the local loader lives in that package.
2. Set `kernel_config.use_local_kernel = False` / avoid local-kernel configs if you cannot install it.
3. Gate the code path on `is_kernels_available()`.

Example fix

# before
repo = LocalLayerRepository("/path/to/kernels")  # RuntimeError

# after
from transformers.utils.import_utils import is_kernels_available
assert is_kernels_available(), "pip install kernels"
repo = LocalLayerRepository("/path/to/kernels")

from transformers.utils.import_utils import is_kernels_available
assert is_kernels_available(), "local kernels still require the kernels package",
repo = LocalLayerRepository("/path/to/kernels")

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

try:
    repo = LocalLayerRepository(path)
except RuntimeError as e:
    if "kernels" in str(e):
        repo = LayerRepository(hub_repo_id) if is_kernels_available() else None
    else:
        raise

When it happens

Trigger: Constructing `LocalLayerRepository(...)` (e.g. `use_local_kernel` flows where a model config points at local kernel directories) while `kernels` is not installed.

Common situations: Offline/air-gapped deployments that deliberately use local kernels but where the `kernels` package was omitted from the environment; sharing configs with `use_local_kernel=True` across machines.

Related errors

• LayerRepository requires `kernels` to be installed. Run `pip
• FuncRepository requires `kernels` to be installed. Run `pip
• replace_kernel_forward_from_hub requires `kernels` to be ins
• register_kernel_mapping requires `kernels` to be installed.
• register_kernel_mapping_transformers requires `kernels` to b

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