kernels/pr_513/en/api/kernels.md

# Kernels API Reference

## Main Functions

### get_kernel[[kernels.get_kernel]]

#### kernels.get_kernel[[kernels.get_kernel]]

[Source](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L291)

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:
```python
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*, defaults to `"main"`) : 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`.

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`) : Boolean flag indicating if the kernel should be trusted. If the kernel is from a trusted publisher then this flag is ignored.

**Returns:**

``ModuleType``

The imported kernel module.

### get_local_kernel[[kernels.get_local_kernel]]

#### kernels.get_local_kernel[[kernels.get_local_kernel]]

[Source](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L355)

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](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L388)

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*, defaults to `"main"`) : 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`.

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_loaded_kernels[[kernels.get_loaded_kernels]]

#### kernels.get_loaded_kernels[[kernels.get_loaded_kernels]]

[Source](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L82)

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:
```python
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](/docs/kernels/pr_513/en/api/kernels#kernels.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](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L428)

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.

**Returns:**

``ModuleType``

The imported kernel module.

### get_locked_kernel[[kernels.get_locked_kernel]]

<<<<<<< kernels-use-kernels-data
#### kernels.get_locked_kernel[[kernels.get_locked_kernel]]

[Source](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L498)

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](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L52)

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](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L37)

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.

=======
#### kernels.get_locked_kernel[[kernels.get_locked_kernel]]

[Source](https://github.com/huggingface/kernels/blob/vr_513/kernels/src/kernels/utils.py#L498)

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.

>>>>>>> main