kernels/pr_675/en/api/kernels.md

Kernels API Reference

Main Functions

get_kernel[[kernels.get_kernel]]

• repo_id (str) -- The Hub repository containing the kernel.
• revision (str, optional) -- The specific revision (branch, tag, or commit) to download. Cannot be used together with version.
• version (int, optional) -- The kernel version to download. Cannot be used together with revision. Either version or revision must be specified.
• backend (str, optional) -- The backend to load the kernel for. Can only be cpu or the backend that Torch is compiled for. The backend will be detected automatically if not provided.
• user_agent (Union[str, dict], optional) -- The user_agent info to pass to snapshot_download() for internal telemetry.
• trust_remote_code (bool | list[str], optional, defaults to False) -- Whether to allow loading kernels from untrusted organisations. When False, only kernels from trusted organisations are allowed. When True, all repositories are allowed. A list of strings will be used to verify signing identities in a future release; for now it emits a warning and falls back to the default trust check.ModuleTypeThe imported kernel module.

Load a kernel from the kernel hub.

This function downloads a kernel to the local Hugging Face Hub cache directory (if it was not downloaded before) and then loads the kernel.

Example:

import torch
from kernels import get_kernel

activation = get_kernel("kernels-community/relu", version=1)
x = torch.randn(10, 20, device="cuda")
out = torch.empty_like(x)
result = activation.relu(out, x)

get_local_kernel[[kernels.get_local_kernel]]

• repo_path (Path) -- The local path to the kernel repository.
• backend (str, optional) -- The backend to load the kernel for. Can only be cpu or the backend that Torch is compiled for. The backend will be detected automatically if not provided.ModuleTypeThe imported kernel module.

Import a kernel from a local kernel repository path.

has_kernel[[kernels.has_kernel]]

• repo_id (str) -- The Hub repository containing the kernel.
• revision (str, optional) -- The specific revision (branch, tag, or commit) to download. Cannot be used together with version.
• version (int, optional) -- The kernel version to download. Cannot be used together with revision. Either version or revision must be specified.
• backend (str, optional) -- The backend to load the kernel for. Can only be cpu or the backend that Torch is compiled for. The backend will be detected automatically if not provided.bool``True if a kernel is available for the current environment.

Check whether a kernel build exists for the current environment (Torch version and compute framework).

get_kernel_variants[[kernels.get_kernel_variants]]

• repo_id (str) -- The Hub repository containing the kernel.
• revision (str, optional) -- The specific revision (branch, tag, or commit) to inspect. Cannot be used together with version.
• version (int, optional) -- The kernel version to inspect. Cannot be used together with revision. Either version or revision must be specified.
• backend (str, optional) -- The backend to resolve variants for. Can only be cpu or the backend that Torch is compiled for. The backend will be detected automatically if not provided.list[Decision]One VariantAccepted or VariantRejected per build variant in the repository, compatible variants first.

Resolve all build variants of a kernel against the current environment.

The decisions are sorted with compatible variants first, the most preferred variant leading.

Example:

from kernels import get_kernel_variants, VariantAccepted

for decision in get_kernel_variants("kernels-community/activation", version=1):
    name = decision.variant.variant_str
    if isinstance(decision, VariantAccepted):
        print(f"{name}: compatible")
    else:
        print(f"{name}: rejected ({decision.reason})")

get_loaded_kernels[[kernels.get_loaded_kernels]]

list[LoadedKernel]One LoadedKernel per distinct kernel variant path loaded in this process.

Return a snapshot of every kernel that has been loaded into the current process.

The returned list is a new list; mutating it does not affect the registry.

Example:

from kernels import get_kernel, get_loaded_kernels

get_kernel("kernels-community/activation", version=1)
for loaded in get_loaded_kernels():
    print(loaded.metadata.name, loaded.repo_info)

Loading locked kernels

load_kernel[[kernels.load_kernel]]

• repo_id (str) -- The Hub repository containing the kernel.
• lockfile (Path, optional) -- Path to the lockfile. If not provided, the lockfile will be loaded from the caller's package metadata.
• backend (str, optional) -- The backend to load the kernel for. Can only be cpu or the backend that Torch is compiled for. The backend will be detected automatically if not provided.
• revision (str, optional) -- The specific revision (branch, tag, or commit) to download. Cannot be used together with version.ModuleTypeThe imported kernel module.

Get a pre-downloaded, locked kernel.

If lockfile is not specified, the lockfile will be loaded from the caller's package metadata.

get_locked_kernel[[kernels.get_locked_kernel]]

• repo_id (str) -- The Hub repository containing the kernel.
• local_files_only (bool, optional, defaults to False) -- Whether to only use local files and not download from the Hub.ModuleTypeThe imported kernel module.

Get a kernel using a lock file.

Classes

LoadedKernel[[kernels.LoadedKernel]]

This dataclass provides information about a loaded kernel:

• metadata (Metadata): kernel metadata.
• module (ModuleType): the imported kernel module.
• repo_info (kernels.utils.RepoInfo | None): populated only for kernels loaded via get_kernel. Loaders that work from a local path (get_local_kernel) or a lockfile (get_locked_kernel, load_kernel) leave this as None.

The metadata includes the following properties that describe a kernel:

• id (str): kernel identifier that is unique to the kernel version + backend.
• name (str): the name of the kernel.
• version (int): the version of the kernel.
• license (str): the license of the kernel.
• upstream (str | None): the original upstream repository of the kernel.
• source (str | None): the kernel-builder formatted source repository.
• python_depends (list[str]): required Python dependencies.
• backend: information about the kernel's backend.

RepoInfo[[kernels.RepoInfo]]

This dataclass stores the origin of the kernel.

The following fields are available:

• repo_id (str): the Hub repository containing the kernel.
• revision (str): the specific revision of the kernel.