huggingface/transformers · error · ImportError

`kernels` is either not installed or uses an incompatible ve

Error message

`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}`

What it means

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.

Source

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

    Args:
        attn_implementation: A string, usually a kernel repo like "kernels-community/flash-mla".
        attn_wrapper: a callable for the wrapper around the attention implementation. In `transformers` we
            have a wrapper around the `flash_attn_var_len` call, and the same goes for `sdpa` and `eager`.
            They just prepare the arguments properly. This is mostly used for continuous batching, where we
            want the `paged` wrapper, which calls the paged cache.
        allow_all_kernels (`bool`, optional):
            Whether to load kernels from unverified hub repos, if it is a custom kernel outside of the `kernels-community`
            hub repository.
    """
    from ..masking_utils import ALL_MASK_ATTENTION_FUNCTIONS
    from ..modeling_utils import ALL_ATTENTION_FUNCTIONS

    actual_attn_name = attn_implementation.split("|")[1] if "|" in attn_implementation else attn_implementation
    if not is_kernel(actual_attn_name):
        return None
    if not is_kernels_available():
        raise ImportError(_MISSING_KERNELS_MESSAGE)

    # Extract repo_id and kernel_name from the string
    if ":" in actual_attn_name:
        repo_id, kernel_name = actual_attn_name.split(":")
        kernel_name = kernel_name.strip()
    else:
        repo_id = actual_attn_name
        kernel_name = None
    repo_id = repo_id.strip()
    # extract the rev after the @ if it exists
    repo_id, _, rev = repo_id.partition("@")
    repo_id = repo_id.strip()

    # create revision xor version
    rev = rev.strip() if rev else None
    version = None
    if rev is None:
        # FA4 is still in beta -> redirect to v0 else default to v1

View on GitHub (pinned to a597f97485)

Solutions

  1. Install a compatible version: `pip install kernels==<KERNELS_MIN_VERSION>` (the message names the exact pinned version).
  2. Check what you have: `pip show kernels` and compare against the range in the message.
  3. If you cannot install it, fall back to a built-in implementation: `attn_implementation="sdpa"` or `"flash_attention_2"`.

Example fix

# before
model = AutoModelForCausalLM.from_pretrained(m, attn_implementation="kernels-community/flash-attn")
# ImportError

# after (option A)
# pip install kernels==<min-version>
model = AutoModelForCausalLM.from_pretrained(m, attn_implementation="kernels-community/flash-attn")

# after (option B: no kernels)
model = AutoModelForCausalLM.from_pretrained(m, attn_implementation="sdpa")
Defensive patterns

Strategy: fallback

Validate before calling

from transformers.utils.import_utils import is_kernels_available
attn = "kernels-community/flash-attn"
if not is_kernels_available():
    attn = "sdpa"  # or "flash_attention_2"
model = AutoModelForCausalLM.from_pretrained(m, attn_implementation=attn)

Type guard

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

Try / catch

try:
    model = AutoModelForCausalLM.from_pretrained(m, attn_implementation="kernels-community/flash-attn")
except ImportError as e:
    if "kernels" in str(e):
        model = AutoModelForCausalLM.from_pretrained(m, attn_implementation="sdpa")
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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