Buckets:

|
download
raw
10.3 kB
# Kernels cache
`kernels` downloads a kernel build from the Hub the first time you load it and
then loads it from a local cache. Later loads of the same kernel, revision and
build variant are served from that cache, so the kernel files are downloaded
only once.
The kernels cache is a regular Hugging Face Hub cache: kernel repositories live
in the same directory as `models--…` and `datasets--…` repositories, and they
use the same layout (`refs/`, `blobs/`, `snapshots/`). This page describes how
the cache is configured, what is stored in it, and how to use it when the Hub
is not reachable.
## Cache location
The cache directory is resolved in this order, first match wins:
| Setting | Cache directory |
| --------------------------- | ---------------------------------------- |
| `KERNELS_CACHE` | `$KERNELS_CACHE` |
| `HF_HUB_CACHE` | `$HF_HUB_CACHE` |
| `HUGGINGFACE_HUB_CACHE` | `$HUGGINGFACE_HUB_CACHE` |
| `HF_HOME` | `$HF_HOME/hub` |
| None of the above | `$XDG_CACHE_HOME/huggingface/hub`, or `~/.cache/huggingface/hub` when `XDG_CACHE_HOME` is not set |
`KERNELS_CACHE` is the only setting that is specific to `kernels`. Set it when
you want kernel builds somewhere other than the cache of your models, for
example on a fast local disk of a GPU machine, on a shared volume, or in a
directory that is baked into a container image:
```bash
export KERNELS_CACHE=/mnt/fast-disk/kernels
```
When `KERNELS_CACHE` is set, it is used only by `kernels`. Other Hugging Face
tools keep using the Hub cache, so kernels stored in `KERNELS_CACHE` are not
visible to them, and `hf cache` commands do not list them.
A few details on how the setting is read:
- A leading `~` is expanded to your home directory.
- An empty value counts as unset.
- The variable is read on every call, not at import time. You can change
`KERNELS_CACHE` (or `os.environ["KERNELS_CACHE"]`) between two `get_kernel`
calls and the second call uses the new directory.
Kernels are downloaded with the same credentials as any other Hub download:
`HF_TOKEN`, or the token written by `hf auth login`. A private kernel
repository is cached like any public kernel, so on a shared machine keep the
cache directory readable only by you.
If you use a Hub mirror through `HF_ENDPOINT`, kernels are downloaded from the
mirror; the cache location is unaffected.
## On-disk layout
Kernel repositories use the `kernels--<org>--<name>` prefix. A cache holding
one version of [`kernels-community/activation`](https://huggingface.co/kernels-community/activation)
looks like this:
```text
<cache-dir>/
├── kernels--kernels-community--activation/
│ ├── refs/
│ │ ├── main
│ │ └── v1
│ ├── blobs/
│ │ └── 9f2c1d… # file contents, addressed by hash
│ └── snapshots/
│ └── 4d1a8e…/ # one directory per downloaded commit
│ └── build/
│ └── torch28-cxx11-cu128-x86_64-linux/
│ ├── metadata.json
│ └── activation/
│ └── __init__.py
└── .verified-kernels/
├── digest/v1/
└── signature/v1/
```
### `snapshots/`
Each downloaded revision gets one snapshot directory, named after its commit.
The directory is a checkout of that commit that only contains the files that
were actually downloaded. Kernels are downloaded by commit, and `kernels` only
fetches the build variant that matches your system (`build/<variant>/*`), so a
snapshot typically holds a single variant even when the repository has many.
To populate more than one variant, use [`kernels download`](cli-download)
with `--all-variants`, which is useful for building a cache that is shared
between machines with different hardware or PyTorch versions.
### `blobs/`
File contents, addressed by their hash. Entries in a snapshot are symlinks into
`blobs/` (copies on systems where symlinks are not available), so two revisions
that share a file also share its blob and the space it takes.
### `refs/`
Maps a branch or tag, such as `v1`, to the commit it points at. Since kernels
are downloaded by commit, `snapshot_download` would not create these refs on its
own. `kernels` therefore records the ref itself when a kernel is fetched by
version or revision, which is what makes `get_kernel(..., version=1)` resolvable
later without a Hub request (see [offline use](#offline-use)).
Refs are a local mirror of the Hub branches and tags and can be deleted: they
are rewritten the next time the kernel is downloaded while online. Deleting a
ref only breaks resolving that branch or tag from the local cache.
### `.verified-kernels/`
Verification receipts. A kernel that has been verified once gets a receipt, so
that its files are not hashed and its signature is not verified again on every
load. Receipts live at the top of the cache directory, not inside a repository,
and are keyed by repo ID, commit and build variant. Deleting them is safe; the
kernel is simply verified in full again on the next load. Since receipts are
stored inside the cache directory, pointing `KERNELS_CACHE` at a different
directory also means the kernels there are verified again. See
[Kernels security](security) for what is verified and what the receipts
attest.
## Inspecting the cache
[`kernels cache ls`](cli-cache) lists the cached kernel versions with their
build variants, sizes and access times:
```bash
kernels cache ls
```
```text
ID SIZE LAST_ACCESSED LAST_MODIFIED VERSION VARIANTS
----------------------------------- ---- -------------- -------------- ------- --------------------------------
kernel/kernels-community/activation 2.5M 45 minutes ago 45 minutes ago v1 torch28-cxx11-cu126-x86_64-linux
torch28-cxx11-cu128-x86_64-linux
```
Use `--json` for machine-readable output, `--cache-dir` to inspect a cache other
than the one currently configured, and `--no-truncate` to see full values when
the table is shortened to fit your terminal. If the cache contains
inconsistencies, the command prints a short summary; `--show-warnings` shows the
details. The command works on the local cache only and does not download or load
kernel code.
## Offline use
Set `HF_HUB_OFFLINE=1` to make `kernels` resolve everything from the local
cache, without Hub requests:
```bash
export HF_HUB_OFFLINE=1
```
In offline mode, kernel versions and revisions are resolved from `refs/`, and
the build variant is taken from the local snapshot. The kernel must already be
in the cache. The simplest way to populate it is to load the kernel once while
online:
```python
from kernels import get_kernel
get_kernel("kernels-community/activation", version=1)
```
This writes the `v1` ref as well, so that `version=1` can be resolved offline
later. If your project [locks its kernels](locking), run
[`kernels download`](cli-download) instead:
```bash
kernels download .
```
A locked project needs no refs offline, since the commit comes from
`kernels.lock`. Add `--all-variants` to cache every build variant rather than
only the one for the current system, which is what you want when the cache is
shared with machines that have a different GPU or PyTorch version.
If the kernel is not cached, loading fails with a clear message. For a version:
```text
Version 1 of 'kernels-community/activation' is not available in the local cache
and Hugging Face Hub is in offline mode. Download the kernel while online first,
or pass an explicit `revision=<commit>`.
```
and for a branch or tag:
```text
Cannot resolve revision 'v1' of 'kernels-community/activation' to a commit: the
ref is not in the local cache and Hugging Face Hub is in offline mode. Download
the kernel while online first, or pass an explicit `revision=<commit>`.
```
Passing an explicit commit with `revision=<commit>`, or loading a locked kernel,
needs no ref lookup, so it works offline as long as that commit's snapshot is
cached.
> [!NOTE]
> The publisher trust check cannot be performed offline. When loading from the
> cache in offline mode, `kernels` skips the check and logs a warning. Trust was
> established when the kernel was downloaded.
To bake a cache into an image, populate it during the build and point
`KERNELS_CACHE` (or `HF_HOME`) at the resulting directory at runtime:
```dockerfile
ENV KERNELS_CACHE=/opt/kernels-cache
RUN python -c 'from kernels import get_kernel; get_kernel("kernels-community/activation", version=1)'
ENV HF_HUB_OFFLINE=1
```
The Python API can also be kept offline-only per call, without the environment
variable, with `install_kernel`:
```python
from kernels import install_kernel
variant_path = install_kernel("kernels-community/activation", version=1, local_files_only=True)
```
## Cleaning up
- Removing a `kernels--…` directory from the cache is safe. The kernel is
downloaded again the next time it is loaded, so this is the way to reclaim
space or to force a fresh download.
- Removing `.verified-kernels/` only costs re-verification on the next load.
- When copying or moving a cache, preserve symlinks (`cp -a`, `tar`, `rsync -a`)
to keep blobs deduplicated. Copying with symlinks resolved also works, but
stores every file once per snapshot.
- The cache is trusted input. Editing files in place is not supported: a
modified file makes digest verification fail the next time the kernel is
verified in full.
## See also
- [Environment variables](env) - `KERNELS_CACHE`, `HF_HUB_OFFLINE` and other settings
- [`kernels cache ls`](cli-cache) - List cached kernels, versions and variants
- [`kernels download`](cli-download) - Pre-populate the cache for locked kernels
- [Lock kernel versions](locking) - Pin commits so no version lookup is needed
- [Kernels security](security) - Verification and receipts
- [Hugging Face Hub cache reference](https://huggingface.co/docs/huggingface_hub/package_reference/cache) - The cache structures that kernels reuse

Xet Storage Details

Size:
10.3 kB
·
Xet hash:
a7f4d62a490a1405ccea614a02fad9ee393a88c2a359e53b895cee3a65068913

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.