Skip to content

Record minimum required kernels version in build metadata (based on features used) #800

Closed

Description

@moon-bot-app

Problem

A kernel build can rely on metadata/features that only newer versions of the kernels library understand (e.g. kernel-depends / kernel-to-kernel dependencies, new backend descriptors, new digest or provenance fields). Today metadata.json — e.g. flash-attn2 v3 — has no notion of which kernels version is needed to consume it:

{
  "name": "flash-attn2",
  "version": 3,
  "python-depends": [],
  "kernel-depends": [],
  "backend": { "type": "cuda", "archs": ["8.0", "9.0"] },
  ...
}

So a user on an older kernels release that loads such a build either silently ignores the fields it doesn't know about or fails with a confusing error, instead of being told "upgrade kernels to >= X".

Proposal

  1. Have the builder emit a minimum-required-kernels version in metadata.json, e.g. "requires-kernels": ">=0.12", computed from the features actually used by the build (kernel deps present → bump the floor; only basic fields → keep the floor low so old clients keep working).
  2. In kernels, check that field at load time and raise a clear, actionable error when the installed version is too old:
    Kernel 'kernels-community/flash-attn2' (revision v3) requires kernels >= 0.12, but 0.9.1 is installed. Please upgrade: pip install -U kernels
    
  3. Treat a missing field as "no constraint" for backwards compatibility with already-published builds.

This complements #744 (suggesting a newer kernel version when no compatible variant exists) — here the mismatch is on the library side rather than the build-variant side.

Follow-ups discussed

  • Verify the kernel-to-kernel dependency feature doesn't break the Transformers kernels tests (check with Anton).
  • The emitting side likely lives in kernel-builder; the consuming/validation side in kernels. Feel free to split this issue if the builder change is tracked separately.

Requested by Sayak Paul - Slack thread - Agent trace

Activity

  1. mukeshbhandarkar commented on Sep 1, 2026

    @mukeshbhandarkar

    I took a look through the metadata and loading paths for this issue, and I think there’s a fairly clean way to split the work.

    Metadata lives in kernels-data, and since it already tolerates unknown fields, adding an optional requires-kernels field should keep existing metadata backward compatible.

    For the Python side, resolve_kernel_tree() seems like a good place to check the requirement. It would cover the root kernel as well as transitive kernel dependencies, and it happens before the full variant is downloaded/imported.

    For kernel-builder, metadata generation is already fairly centralized, so the requirement could be derived per variant based on the features it actually uses (for example, kernel-depends).

    I was thinking of doing this in two steps:

    1. Add the optional metadata field + validation in kernels, with tests.
    2. Add the builder logic that emits the requirement once the consumer side is in place.

    Before I start working on it, I wanted to check a few details:

    • Should requires-kernels support normal PEP 440 specifiers like >=0.12, or should it only represent a minimum version?
    • If the value is malformed, should loading fail?
    • Would you prefer the check during dependency-tree resolution, just before import, or both?
    • Should locking / install_kernel_all_variants also enforce it?
    • For kernel-depends, which kernels release should be considered the minimum supported version?

    If this direction makes sense, I’d be happy to start with the metadata + consumer validation part.

  2. danieldk commented on Sep 2, 2026

    @danieldk
    Member

    Fixed by #801.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions