kernels/pr_607/en/api/kernels.md

Kernels API Reference

Main Functions

get_kernel[[kernels.get_kernel]]

kernels.get_kernel[[kernels.get_kernel]]

Source

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)

Parameters:

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.

Returns:

*ModuleType*

The imported kernel module.

get_local_kernel[[kernels.get_local_kernel]]

kernels.get_local_kernel[[kernels.get_local_kernel]]

Source

Import a kernel from a local kernel repository path.

Parameters:

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.

Returns:

ModuleType

The imported kernel module.

has_kernel[[kernels.has_kernel]]

kernels.has_kernel[[kernels.has_kernel]]

Source

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

Parameters:

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.

Returns:

bool

True if a kernel is available for the current environment.

get_kernel_variants[[kernels.get_kernel_variants]]

kernels.get_kernel_variants[[kernels.get_kernel_variants]]

Source

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

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

Parameters:

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.

Returns:

list[Decision]

One VariantAccepted or VariantRejected per build variant in the repository, compatible variants first.

get_loaded_kernels[[kernels.get_loaded_kernels]]

kernels.get_loaded_kernels[[kernels.get_loaded_kernels]]

Source

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)

Returns:

list[LoadedKernel]

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

Loading locked kernels

load_kernel[[kernels.load_kernel]]

kernels.load_kernel[[kernels.load_kernel]]

Source

Get a pre-downloaded, locked kernel.

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

Parameters:

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.

Returns:

ModuleType

The imported kernel module.

get_locked_kernel[[kernels.get_locked_kernel]]

kernels.get_locked_kernel[[kernels.get_locked_kernel]]

Source

Get a kernel using a lock file.

Parameters:

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.

Returns:

ModuleType

The imported kernel module.

Classes

LoadedKernel[[kernels.LoadedKernel]]

kernels.LoadedKernel[[kernels.LoadedKernel]]

Source

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 upstream repository of the kernel.
• python_depends (list[str]): required Python dependencies.
• backend: information about the kernel's backend.

RepoInfo[[kernels.RepoInfo]]

kernels.RepoInfo[[kernels.RepoInfo]]

Source

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.