add init command that pulls template repo by drbh · Pull Request #247 · huggingface/kernels

drbh · 2026-01-28T17:38:20Z

this PR adds a new init subcommand that clones a huggingface

kernels init drbh/my-kernel

outputs

Downloading template from drbh/template...
Initialized kernel project: /Users/drbh/Projects/kernels/my-kernel
├── my_kernel_cpu
│   └── my_kernel_cpu.cpp
├── my_kernel_cuda
│   └── my_kernel.cu
├── my_kernel_metal
│   ├── my_kernel.metal
│   └── my_kernel.mm
├── my_kernel_xpu
│   └── my_kernel.cpp
├── tests
│   ├── __init__.py
│   └── test_my_kernel.py
├── torch-ext
│   ├── my_kernel
│   │   └── __init__.py
│   ├── torch_binding.cpp
│   └── torch_binding.h
├── .gitattributes
├── .gitignore
├── README.md
├── build.toml
├── example.py
└── flake.nix

Next steps:
  cd my-kernel
  nix run .#build-and-copy -L
  uv run example.py

now build

cd my-kernel
nix run .#build-and-copy -L

# tree build -L 1
# build
# ├── torch210-cpu-aarch64-darwin
# ├── torch210-metal-aarch64-darwin
# ├── torch29-cpu-aarch64-darwin
# └── torch29-metal-aarch64-darwin

# 5 directories, 0 files

then run

uv run example.py

outputs

Using device: mps
Input:  tensor([1., 2., 3.], device='mps:0')
Output: tensor([2., 3., 4.], device='mps:0')
Success!

and tested on a cuda device

# ... same commands as above

# tree build -L 1
# build
# ├── torch210-cxx11-cpu-x86_64-linux
# ├── torch210-cxx11-cu126-x86_64-linux
# ├── torch210-cxx11-cu128-x86_64-linux
# ├── torch210-cxx11-cu130-x86_64-linux
# ├── torch210-cxx11-rocm70-x86_64-linux
# ├── torch210-cxx11-rocm71-x86_64-linux
# ├── torch210-cxx11-xpu20253-x86_64-linux
# ├── torch29-cxx11-cpu-x86_64-linux
# ├── torch29-cxx11-cu126-x86_64-linux
# ├── torch29-cxx11-cu128-x86_64-linux
# ├── torch29-cxx11-cu130-x86_64-linux
# ├── torch29-cxx11-rocm63-x86_64-linux
# ├── torch29-cxx11-rocm64-x86_64-linux
# └── torch29-cxx11-xpu20252-x86_64-linux

# 14 directories, 0 files

outputs

Using device: cuda
Input:  tensor([1., 2., 3.], device='cuda:0')
Output: tensor([2., 3., 4.], device='cuda:0')
Success!

HuggingFaceDocBuilderDev · 2026-01-28T17:39:54Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

danieldk

Nice!!!

drbh · 2026-01-29T19:30:17Z

updates

uname -a
# Darwin Mac 25.2.0 Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:41 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6031 arm64
kernels init drbh/my-kernel

now clones the repo and removes the non platform specific dirs, and updates the build.toml to only contain the detected or specified backend.

output

Downloading template from drbh/template...
Initialized kernel project: /Users/drbh/Projects/kernel-init-tmp/my-kernel
├── my_kernel_metal
│   ├── my_kernel.metal
│   └── my_kernel.mm
├── tests
│   ├── __init__.py
│   └── test_my_kernel.py
├── torch-ext
│   ├── my_kernel
│   │   └── __init__.py
│   ├── torch_binding.cpp
│   └── torch_binding.h
├── .gitattributes
├── .gitignore
├── README.md
├── build.toml
├── example.py
└── flake.nix

Next steps:
  cd my-kernel
  cachix use huggingface
  nix run -L --max-jobs 1 --cores 8 .#build-and-copy
  uv run example.py

build toml file

[general]
backends = ["metal"]
name = "my-kernel"
version = 1

[torch]
src = [
  "torch-ext/torch_binding.cpp",
  "torch-ext/torch_binding.h",
]

[kernel.my_kernel_metal]
backend = "metal"
depends = ["torch"]
src = [
  "my_kernel_metal/my_kernel.mm",
  "my_kernel_metal/my_kernel.metal",
]

help message shows

kernels init --help

usage: kernel init [-h] [--template-repo TEMPLATE_REPO]
                   [--backends BACKENDS [BACKENDS ...]]
                   kernel_name

positional arguments:
  kernel_name           Name of the kernel repo (e.g., drbh/my-
                        kernel)

options:
  -h, --help            show this help message and exit
  --template-repo TEMPLATE_REPO
                        HuggingFace repo ID for the template
  --backends BACKENDS [BACKENDS ...]
                        Backends to include ('all' or list like: cpu
                        cuda metal rocm xpu). Defaults: cuda on
                        Linux/Windows, metal on macOS.

danieldk · 2026-01-30T17:50:05Z

kernels/src/kernels/init.py

+        backends = ["metal"] if sys.platform == "darwin" else ["cuda"]
+    else:
+        backends = [
+            v.strip().lower()


Is stripping and lowercasing needed? I think all the whitespace should be consumed by the argument parser. I think it's better if people just have to give the arguments in lowercase.

great suggestion the code is much cleaner in the latest commit, thanks!

danieldk · 2026-01-30T17:52:55Z

kernels/src/kernels/cli.py

+    init_parser.add_argument(
+        "--backends",
+        nargs="+",
+        default=None,


I think we can use action="extend" and then the user can use something like --backends cuda rocm.

ended up using "+" instead of extend so if a user specifies a backend it overrides the default, otherwise we default to metal on darwin and cuda in all other cases

danieldk · 2026-01-30T17:53:17Z

kernels/src/kernels/init.py

+        backends = [
+            v.strip().lower()
+            for item in args.backends
+            for v in item.split(",")


See above, I don't think we need extra parsing, we can let argparse handle it.

same as above, updated in latest commit

danieldk · 2026-01-30T17:55:08Z

kernels/src/kernels/cli.py

+        "--backends",
+        nargs="+",
+        default=None,
+        help="Backends to include ('all' or list like: cpu cuda metal rocm xpu). Defaults: cuda on Linux/Windows, metal on macOS.",


Since this is a finite list, it would be nice to use choices=.... We can also set the default to cuda or metal here. I think argparse will then even show it in the usage.

same as above, updated in latest commit

danieldk · 2026-01-30T17:55:19Z

kernels/src/kernels/init.py

 def run_init(args: Namespace) -> None:
    kernel_name = args.kernel_name
+    if args.backends is None:
+        backends = ["metal"] if sys.platform == "darwin" else ["cuda"]


same as above, updated in latest commit

danieldk · 2026-01-30T17:55:40Z

kernels/src/kernels/init.py

+                sys.exit(1)
+            backends = []
+        else:
+            valid = set(KNOWN_BACKENDS)


See above, best to let argparse do the work.

fully agree, same as above, updated in latest commit

danieldk · 2026-01-30T17:58:03Z

kernels/src/kernels/init.py

+    text = build_toml_path.read_text()
+    with open(build_toml_path, "rb") as f:
+        data = tomllib.load(f)
+        if "general" not in data:
+            return
+    kernel_table = data.get("kernel", {})
+    if not isinstance(kernel_table, dict):
+        kernel_table = {}
+    remove_kernels = {
+        name
+        for name, cfg in kernel_table.items()
+        if isinstance(cfg, dict) and cfg.get("backend") not in set(backends)
+    }
+    backends_list = ", ".join(f'"{b}"' for b in backends)
+    new_line = f"backends = [{backends_list}]"
+    pattern = r"(\[general\][\s\S]*?)^\s*backends\s*=\s*\[[^\]]*\]"
+    new_text, count = re.subn(pattern, r"\1" + new_line, text, count=1, flags=re.M)
+    if remove_kernels:
+        new_text = _remove_kernel_sections(new_text, remove_kernels)
+    if count or remove_kernels:
+        build_toml_path.write_text(new_text)


I think it's cleaner to parse the TOML, modify the Python data structures and then serialize as TOML again. regexps are fragile.

totally agree, the main reason I opt'ed for regex over toml is that I was concerned that writing toml back into the file would lose any comments/formatting added to the template.

I think its a reasonable trade off (more robust toml parsing, instead of comments) however my initial approach attempted to be comment preserving.

happy to update with the toml route, just wanted to flag the reasoning/tradeoff

Maybe we should consider using tomlkit, since it can preserve comments?

great suggestion, I've added tomlkit as a dep in the latest commits. Im still open to using the builtins if we don't see a benefit from preserving comments/whitespace, but the current changes are working well

danieldk · 2026-01-30T18:00:44Z

kernels/src/kernels/utils.py

 from kernels.metadata import Metadata

 ENV_VARS_TRUE_VALUES = {"1", "ON", "YES", "TRUE"}
+KNOWN_BACKENDS = ("cpu", "cuda", "metal", "rocm", "xpu", "npu")


Better to make it a set?

agreed, updated in latest commit

danieldk previously approved these changes Jan 29, 2026

View reviewed changes

drbh dismissed danieldk’s stale review via e7d3188 January 29, 2026 19:24

drbh temporarily deployed to testpypi January 29, 2026 19:24 — with GitHub Actions Inactive

danieldk reviewed Jan 30, 2026

View reviewed changes

drbh force-pushed the add-template-based-init branch from 334be5e to 658b0cc Compare February 3, 2026 16:25

drbh temporarily deployed to testpypi February 3, 2026 16:36 — with GitHub Actions Inactive

drbh temporarily deployed to testpypi February 3, 2026 16:51 — with GitHub Actions Inactive

drbh temporarily deployed to testpypi February 3, 2026 17:07 — with GitHub Actions Inactive

drbh temporarily deployed to testpypi February 3, 2026 17:13 — with GitHub Actions Inactive

drbh added 9 commits February 3, 2026 13:32

feat: add init command that pulls template repo

3070c7c

fix: suppress download logs

8680d0c

fix: include cachix command to speed up nix build

28751ab

fix: suggest limited cores and jobs when building example to avoid oom

3bfe957

fix: detect and default template for platform

515c26c

fix: simplify init logic and add test for init

f7c053c

fix: include tomlkit in nix python modules

4fea9d3

fix: prefer pinned tomlkit dep

5efebc3

fix: adjust type ignore for tomlkit on py3.10

8796712

drbh force-pushed the add-template-based-init branch from 60bc1f0 to 8796712 Compare February 3, 2026 18:32

drbh temporarily deployed to testpypi February 3, 2026 18:32 — with GitHub Actions Inactive

Conversation

drbh commented Jan 28, 2026

Uh oh!

HuggingFaceDocBuilderDev commented Jan 28, 2026

Uh oh!

danieldk left a comment

Choose a reason for hiding this comment

Uh oh!

drbh commented Jan 29, 2026

updates

help message shows

Uh oh!

Choose a reason for hiding this comment

Uh oh!

drbh Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

drbh Feb 3, 2026 •

edited

Loading