{"record":{"id":"d9d377b6fc07d92a","repo":"huggingface/transformers","slug":"replace-kernel-forward-from-hub-requires-kernels","errorCode":null,"errorMessage":"replace_kernel_forward_from_hub requires `kernels` to be installed. Run `pip install kernels`.","messagePattern":"replace_kernel_forward_from_hub requires `kernels` to be installed\\. Run `pip install kernels`\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/hub_kernels.py","lineNumber":566,"sourceCode":"\n        def load(self):\n            raise NotImplementedError(\"LayerRepository requires `kernels` to be installed. Run `pip install kernels.\")\n\n    class LocalLayerRepository:\n        def __init__(self, *args, **kwargs):\n            raise RuntimeError(\"LocalLayerRepository requires `kernels` to be installed. Run `pip install kernels`.\")\n\n        def load(self):\n            raise NotImplementedError(\n                \"LocalLayerRepository requires `kernels` to be installed. Run `pip install kernels.\"\n            )\n\n    class FuncRepository:\n        def __init__(self, *args, **kwargs):\n            raise RuntimeError(\"FuncRepository requires `kernels` to be installed. Run `pip install kernels`.\")\n\n    def replace_kernel_forward_from_hub(*args, **kwargs):\n        raise RuntimeError(\n            \"replace_kernel_forward_from_hub requires `kernels` to be installed. Run `pip install kernels`.\"\n        )\n\n    def register_kernel_mapping(*args, **kwargs):\n        raise RuntimeError(\"register_kernel_mapping requires `kernels` to be installed. Run `pip install kernels`.\")\n\n    def register_kernel_mapping_transformers(*args, **kwargs):\n        raise RuntimeError(\n            \"register_kernel_mapping_transformers requires `kernels` to be installed. Run `pip install kernels`.\"\n        )\n\n\n_HUB_KERNEL_MAPPING: dict[str, dict[str, str]] = {\n    \"finegrained-fp8\": {\"repo_id\": \"kernels-community/finegrained-fp8\", \"version\": 4},\n    \"deep-gemm\": {\"repo_id\": \"kernels-community/deep-gemm\", \"version\": 2},\n    \"sonic-moe\": {\"repo_id\": \"kernels-community/sonic-moe\", \"revision\": \"ep-support\"},\n}\n","sourceCodeStart":548,"sourceCodeEnd":584,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/hub_kernels.py#L548-L584","documentation":"`replace_kernel_forward_from_hub` is the decorator that swaps a layer's forward for a Hub kernel implementation. In the fallback block used when `kernels` is missing, the function itself is redefined to raise RuntimeError immediately, so any attempt to use the decorator (or call the function) reports the missing dependency.","triggerScenarios":"Applying `@replace_kernel_forward_from_hub(...)` to a layer class, or calling it, in an environment without `kernels`. Typically triggered by importing kernelized model files that use the decorator at class-definition time.","commonSituations":"Importing a model whose code contains the decorator without the `kernels` extra installed; class-level decorators make this fire at import time, breaking the whole module import.","solutions":["Install `kernels` before importing the kernelized model module.","Ensure the module only applies the decorator when `is_kernels_available()` (the normal transformers pattern guards these imports).","Use a non-kernelized variant of the model if kernels are not an option."],"exampleFix":"# before (module top-level, breaks import without kernels)\n@replace_kernel_forward_from_hub(\"kernels-community/fla\")\nclass MyMambaLayer(MambaLayer): ...\n\n# after\nfrom transformers.utils.import_utils import is_kernels_available\nif is_kernels_available():\n    from transformers.integrations.hub_kernels import replace_kernel_forward_from_hub as _wrap\nelse:\n    _wrap = lambda *a, **k: (lambda cls: cls)\n\n@_wrap(\"kernels-community/fla\")\nclass MyMambaLayer(MambaLayer): ...","handlingStrategy":"fallback","validationCode":"from transformers.utils.import_utils import is_kernels_available\nuse_decorator = is_kernels_available()","typeGuard":null,"tryCatchPattern":"try:\n    import transformers.integrations.hub_kernels as hk\n    assert callable(getattr(hk, \"replace_kernel_forward_from_hub\"))\nexcept Exception:\n    hk = None","preventionTips":["Install kernels before importing modules that use kernel decorators at class-definition time.","Wrap decorator application in a conditional so imports never hard-fail on slim environments."],"tags":["dependencies","kernels","decorator","import-time"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}