{"record":{"id":"63a66f0529aa901e","repo":"huggingface/transformers","slug":"register-kernel-mapping-transformers-requires-ker","errorCode":null,"errorMessage":"register_kernel_mapping_transformers requires `kernels` to be installed. Run `pip install kernels`.","messagePattern":"register_kernel_mapping_transformers 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":574,"sourceCode":"        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.\"\"\"\n    return (\n        attn_implementation is not None\n        and re.search(r\"^[^/:]+/[^/:]+(?:@[^/:]+)?(?::[^/:]+)?$\", attn_implementation) is not None","sourceCodeStart":556,"sourceCodeEnd":592,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/hub_kernels.py#L556-L592","documentation":"`register_kernel_mapping_transformers` pre-registers transformers' own layer-to-kernel mappings; like the other symbols in the fallback block it is a stub raising RuntimeError when `kernels` is absent. The failure is a dependency problem, not a logic problem in your mapping.","triggerScenarios":"Calling `register_kernel_mapping_transformers()` during model/kernel initialization in an environment without `kernels`.","commonSituations":"Startup code that eagerly registers all transformers kernel mappings; environments where transformers was installed without the optional kernels extra but the application unconditionally initializes kernel support.","solutions":["Install `kernels` (pin within the compatible range shown in companion error messages).","Call it only when `is_kernels_available()` returns True.","Verify with `python -c \"import kernels\"` to distinguish not-installed from wrong-version."],"exampleFix":"# before\nregister_kernel_mapping_transformers()  # RuntimeError\n\n# after\nfrom transformers.utils.import_utils import is_kernels_available\nif is_kernels_available():\n    register_kernel_mapping_transformers()","handlingStrategy":"validation","validationCode":"from transformers.utils.import_utils import is_kernels_available\nif is_kernels_available():\n    register_kernel_mapping_transformers()","typeGuard":null,"tryCatchPattern":"try:\n    register_kernel_mapping_transformers()\nexcept RuntimeError as e:\n    if \"kernels\" in str(e):\n        pass  # run without pre-registered transformers kernel mappings\n    else:\n        raise","preventionTips":["Run optional-dependency registration only after an availability check.","Keep transformers and kernels versions aligned to avoid the incompatible-version branch."],"tags":["dependencies","kernels","kernel-mapping","startup"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}