{"record":{"id":"567936329dfca4b5","repo":"huggingface/transformers","slug":"register-kernel-mapping-requires-kernels-to-be-i","errorCode":null,"errorMessage":"register_kernel_mapping requires `kernels` to be installed. Run `pip install kernels`.","messagePattern":"register_kernel_mapping 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":571,"sourceCode":"        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\n_KERNEL_MODULE_MAPPING: dict[str, ModuleType | None] = {}\n\n\ndef is_kernel(attn_implementation: str | None) -> bool:\n    \"\"\"Check whether `attn_implementation` matches a kernel pattern from the hub.\"\"\"","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/hub_kernels.py#L553-L589","documentation":"`register_kernel_mapping` installs a mapping from layer names to Hub kernel repos for the current process. Without the `kernels` package it is a stub that raises RuntimeError on any call, informing you the hub-kernel subsystem is inactive and how to enable it.","triggerScenarios":"Calling `register_kernel_mapping(...)` (common in setup code that wires custom kernels into a model) when `kernels` is not installed.","commonSituations":"Copy-pasted kernel setup snippets into a project whose environment lacks `kernels`; onboarding scripts that register mappings unconditionally.","solutions":["Install `kernels` in a compatible version.","Wrap registration in `if is_kernels_available():`.","Pass kernel mappings via `KernelConfig`/model kwargs only on machines where kernels are set up."],"exampleFix":"# before\nregister_kernel_mapping({\"LlamaDecoderLayer\": \"kernels-community/llama-layer\"})  # RuntimeError\n\n# after\nfrom transformers.utils.import_utils import is_kernels_available\nif is_kernels_available():\n    register_kernel_mapping({\"LlamaDecoderLayer\": \"kernels-community/llama-layer\"})","handlingStrategy":"validation","validationCode":"from transformers.utils.import_utils import is_kernels_available\nif is_kernels_available():\n    register_kernel_mapping(mapping)","typeGuard":null,"tryCatchPattern":"try:\n    register_kernel_mapping(mapping)\nexcept RuntimeError as e:\n    if \"kernels\" in str(e):\n        logging.warning(\"kernels not installed; skipping kernel mapping\")\n    else:\n        raise","preventionTips":["Centralize kernel setup in one function guarded by is_kernels_available().","Add `kernels` to the environment spec for any deployment using hub kernels."],"tags":["dependencies","kernels","kernel-mapping"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}