{"record":{"id":"d3d80bc61e3942de","repo":"huggingface/transformers","slug":"kernels-is-either-not-installed-or-uses-an-incom","errorCode":null,"errorMessage":"`kernels` is either not installed or uses an incompatible version. Please install a compatible version ({KERNELS_MIN_VERSION} <= version < {KERNELS_MAX_VERSION}), e.g. `pip install kernels=={KERNELS_MIN_VERSION}`","messagePattern":"`kernels` is either not installed or uses an incompatible version\\. Please install a compatible version \\((.+?) <= version < (.+?)\\), e\\.g\\. `pip install kernels==(.+?)`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/hub_kernels.py","lineNumber":619,"sourceCode":"\n    Args:\n        attn_implementation: A string, usually a kernel repo like \"kernels-community/flash-mla\".\n        attn_wrapper: a callable for the wrapper around the attention implementation. In `transformers` we\n            have a wrapper around the `flash_attn_var_len` call, and the same goes for `sdpa` and `eager`.\n            They just prepare the arguments properly. This is mostly used for continuous batching, where we\n            want the `paged` wrapper, which calls the paged cache.\n        allow_all_kernels (`bool`, optional):\n            Whether to load kernels from unverified hub repos, if it is a custom kernel outside of the `kernels-community`\n            hub repository.\n    \"\"\"\n    from ..masking_utils import ALL_MASK_ATTENTION_FUNCTIONS\n    from ..modeling_utils import ALL_ATTENTION_FUNCTIONS\n\n    actual_attn_name = attn_implementation.split(\"|\")[1] if \"|\" in attn_implementation else attn_implementation\n    if not is_kernel(actual_attn_name):\n        return None\n    if not is_kernels_available():\n        raise ImportError(_MISSING_KERNELS_MESSAGE)\n\n    # Extract repo_id and kernel_name from the string\n    if \":\" in actual_attn_name:\n        repo_id, kernel_name = actual_attn_name.split(\":\")\n        kernel_name = kernel_name.strip()\n    else:\n        repo_id = actual_attn_name\n        kernel_name = None\n    repo_id = repo_id.strip()\n    # extract the rev after the @ if it exists\n    repo_id, _, rev = repo_id.partition(\"@\")\n    repo_id = repo_id.strip()\n\n    # create revision xor version\n    rev = rev.strip() if rev else None\n    version = None\n    if rev is None:\n        # FA4 is still in beta -> redirect to v0 else default to v1","sourceCodeStart":601,"sourceCodeEnd":637,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/hub_kernels.py#L601-L637","documentation":"While resolving a requested attention implementation, transformers detects the name refers to a hub kernel (`is_kernel(...)` is True) and then requires the `kernels` package to fetch it. `is_kernels_available()` returns False both when `kernels` is absent and when its version is outside the supported range, and the resulting ImportError states the exact accepted version window.","triggerScenarios":"Loading a model with `attn_implementation=\"kernels-community/flash-attn\"` (or any `repo:kernel` / `repo@rev` style name recognized as a kernel) while `kernels` is not installed or is an incompatible version, e.g. after an upgrade pulled kernels==0.0.x outside the supported range.","commonSituations":"Passing hub-kernel attention names popular in optimized-inference examples; version skew where transformers bumps its supported kernels range but the environment has an older/newer `kernels`; fresh environments without the extra.","solutions":["Install a compatible version: `pip install kernels==<KERNELS_MIN_VERSION>` (the message names the exact pinned version).","Check what you have: `pip show kernels` and compare against the range in the message.","If you cannot install it, fall back to a built-in implementation: `attn_implementation=\"sdpa\"` or `\"flash_attention_2\"`."],"exampleFix":"# before\nmodel = AutoModelForCausalLM.from_pretrained(m, attn_implementation=\"kernels-community/flash-attn\")\n# ImportError\n\n# after (option A)\n# pip install kernels==<min-version>\nmodel = AutoModelForCausalLM.from_pretrained(m, attn_implementation=\"kernels-community/flash-attn\")\n\n# after (option B: no kernels)\nmodel = AutoModelForCausalLM.from_pretrained(m, attn_implementation=\"sdpa\")","handlingStrategy":"fallback","validationCode":"from transformers.utils.import_utils import is_kernels_available\nattn = \"kernels-community/flash-attn\"\nif not is_kernels_available():\n    attn = \"sdpa\"  # or \"flash_attention_2\"\nmodel = AutoModelForCausalLM.from_pretrained(m, attn_implementation=attn)","typeGuard":"def hub_kernel_attn_ready() -> bool:\n    from transformers.utils.import_utils import is_kernels_available\n    return is_kernels_available()","tryCatchPattern":"try:\n    model = AutoModelForCausalLM.from_pretrained(m, attn_implementation=\"kernels-community/flash-attn\")\nexcept ImportError as e:\n    if \"kernels\" in str(e):\n        model = AutoModelForCausalLM.from_pretrained(m, attn_implementation=\"sdpa\")\n    else:\n        raise","preventionTips":["Reserve hub-kernel attention names for environments that declare the kernels dependency.","Pin kernels==KERNELS_MIN_VERSION alongside transformers in lockfiles.","Verify with python -c 'import kernels' in deployment smoke tests."],"tags":["dependencies","kernels","attention","version-mismatch"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}