kernels: allow dotted versions in variants, add Python ABI by danieldk · Pull Request #985 · huggingface/kernels

danieldk · 2026-11-10T14:02:00Z

Versions in variant notation were inspired by Torch, which used e.g. cu128 for CUDA 12.8. However, this is fragile (e.g. 714 is parsed as 71.4) and inconsistent (e.g. 215 in torch215 is parsed as 2.15).

This PR

Allows using a dotted version of variants to avoid ambiguities.
A dash is added before the versions for clarity (e.g. torch-2.14 and rocm-2.7).
A Python ABI tag is added in preparation of abi3t support (possible tags: abi3 and abi3t).
cu<major><minor> becomes cuda-<major>.<minor> to use the backend name (similar to the noarch torch-cuda)

Full examples of the new variant notation:

torch-2.14-rocm-7.2-abi3-x86_64-linux
torch-2.14-cuda-13.0-abi3t-x86_64-linux

This change only adds it to the client, we need support to be around for a few iterations before we can roll out kernels dotted versions.

The legacy notation is still supported, so that all existing kernels load.

Breaking change: torch-npu becomes torch-cann. But I don't think there are any kernels out there that actually use it, so it should low-impact.

Versions in variant notation were inspired by Torch, which used e.g. cu128 for CUDA 12.8. However, this is fragile (e.g. 714 is parsed as 71.4) and inconsistent (e.g. 215 in torch215 is parsed as 2.15). This PR allows using a dotted version of variants to avoid ambiguities, such as. We also add a dash before versions for clarity, e.g.: `torch2.10-cu12.8-x86_64-linux` This change only adds it to the client, we need support to be around for a few iterations before we can roll out kernels dotted versions. Breaking change: `torch-npu` becomes `torch-cann`. But I don't think there are any kernels out there that actually use it, so it should low-impact.

HuggingFaceDocBuilderDev · 2026-11-10T14:07:43Z

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.

github-actions · 2026-11-10T14:33:37Z

Coverage report — `kernels/`

Measured on: Python 3.10 / Torch 2.13.0.
Other CI configurations are not included in this number.
Hardware-gated code paths (ROCm/XPU/NPU/Darwin/Windows) are excluded or unreachable on the Linux+CUDA runner.

Total coverage: 89.9% — threshold: 80% — ✅

Per-file breakdown

Name	Stmts	Miss	Cover	Missing
src/kernels/__init__.py	14	0	100%
src/kernels/_system.py	6	1	83%	10
src/kernels/_versions.py	130	14	89%	53, 59-60, 63-64, 102, 165-170, 199, 219
src/kernels/archs.py	56	1	98%	94
src/kernels/backends.py	242	44	82%	95, 138, 147, 156, 190, 199, 270, 286, 290, 294-319, 327, 350-370
src/kernels/compat.py	9	1	89%	5
src/kernels/deps.py	70	1	99%	56
src/kernels/digest.py	58	5	91%	71-73, 136-137
src/kernels/hf_hub.py	62	2	97%	21, 23
src/kernels/importer.py	74	5	93%	158, 162, 165, 179-180
src/kernels/install.py	21	7	67%	76-100
src/kernels/layer/__init__.py	7	0	100%
src/kernels/layer/_interval_tree.py	103	4	96%	23, 52, 147, 150
src/kernels/layer/device.py	48	12	75%	42, 47-49, 91, 96-98, 101, 149, 152, 156
src/kernels/layer/func.py	93	5	95%	94, 119, 195, 315, 390
src/kernels/layer/globals.py	5	0	100%
src/kernels/layer/inspect.py	27	0	100%
src/kernels/layer/kernelize.py	83	7	92%	306, 314-315, 321, 325, 341-343
src/kernels/layer/layer.py	320	14	96%	212, 259, 447, 606-607, 628, 636, 647, 688, 692, 705, 760, 801, 876
src/kernels/layer/mode.py	14	0	100%
src/kernels/layer/repos.py	136	36	74%	32, 35-42, 73, 86, 90, 99-100, 103, 106-109, 116-117, 120, 123-126, 133-134, 137, 140-143, 150-151, 154, 157-160, 235
src/kernels/load.py	71	2	97%	338, 378
src/kernels/locking.py	89	64	28%	35-83, 91-98, 102-125, 137, 152-159, 165-175, 179-186
src/kernels/python_deps.py	58	6	90%	59-60, 64-65, 101, 104
src/kernels/resolver.py	162	1	99%	248
src/kernels/status.py	50	2	96%	25, 79
src/kernels/validate.py	104	7	93%	9, 101, 172, 195-196, 232-233
src/kernels/variants.py	316	9	97%	331-332, 374-377, 379, 536-542
src/kernels/verify.py	102	6	94%	44, 176-178, 266-267
TOTAL	2530	256	90%

Updated by the Test kernels workflow on commit 40b5372d7f86f824982564287ec8f6022dc8d54e.

drbh

lgtm!

sayakpaul · 2026-11-11T07:04:24Z

+    Parse a versioned variant string with the regex for the legacy or the new
+    variant string format. Both regexes capture the major and minor version.
+    """


Maybe also include an example of the legacy and new versions?

Great idea, added some extra docs.

sayakpaul · 2026-11-11T07:13:45Z

+_UNVERSIONED_BACKENDS: dict[str, type[CPU] | type[Metal] | type[Neuron] | type[TPU]] = {
+    "cpu": CPU,
+    "metal": Metal,
+    "neuron": Neuron,
+    "tpu": TPU,
+}
+
+_VERSIONED_BACKENDS: dict[str, type[CANN] | type[CUDA] | type[ROCm] | type[XPU]] = {
+    "cann": CANN,
+    "cuda": CUDA,
+    "rocm": ROCm,
+    "xpu": XPU,
+}


Very cool separation!

sayakpaul · 2026-11-11T07:23:54Z

+    new = parse_variant("torch-2.10-cxx11-cuda-12.8-abi3-x86_64-linux")
+    legacy = parse_variant("torch210-cxx11-cu128-x86_64-linux")
+    assert new == legacy
+    assert hash(new) == hash(legacy)


Fantastic test!

this pr fixes #995 the legacy backend regexes now use named `major`/`minor` captures and rocm special cases 7.14 (`rocm(?P<major>7(?=14$)|\d+)(?P<minor>\d+)`), so `rocm714` parses as 7.14 and every other version keeps the old split `resolve_local_kernel` also keeps the rejection reasons from every pass, previously the `build/` pass replaced them with an empty trace note: the named captures came out of review so the 7.14 special case reads explicitly. it uses a lookahead since python `re` does not allow the same group name twice in an alternation. this only matters for 7.14 since kernel-builder builds no other two-digit minor, the dotted format from #985 avoids it going forward another note: the trace change is not needed for the parse fix, it only changes the error message. without it the ci error ended in an empty list instead of the rocm version rejection, which is what made this hard to track down new cases in `test_parse_backend_formats` and a regression test for the trace, both fail without the fix --------- Signed-off-by: David Holtz <david.richard.holtz@gmail.com>

danieldk marked this pull request as draft November 10, 2026 14:17

kernels: also add Python ABI marker while we update the format

40b5372

danieldk changed the title ~~kernels: allow dotted versions in variants~~ kernels: allow dotted versions in variants, add Python ABI Nov 10, 2026

danieldk marked this pull request as ready for review November 10, 2026 15:00

drbh approved these changes Nov 10, 2026

View reviewed changes

sayakpaul approved these changes Nov 11, 2026

View reviewed changes

danieldk merged commit e475890 into main Nov 11, 2026
55 checks passed

danieldk deleted the dotted-version-variants branch November 11, 2026 08:40

drbh mentioned this pull request Nov 12, 2026

fix: parse rocm714 legacy variants as rocm 7.14 #996

Merged

Navigation Menu

Repository navigation

kernels: allow dotted versions in variants, add Python ABI - #985

kernels: allow dotted versions in variants, add Python ABI#985
danieldk merged 2 commits into
mainfrom
dotted-version-variants

danieldk commented Nov 10, 2026 •

edited

Loading

Uh oh!

HuggingFaceDocBuilderDev commented Nov 10, 2026

Uh oh!

github-actions Bot commented Nov 10, 2026 •

edited

Loading

Uh oh!

drbh left a comment

Uh oh!

sayakpaul Nov 11, 2026

Uh oh!

danieldk Nov 11, 2026

Uh oh!

sayakpaul Nov 11, 2026

Uh oh!

sayakpaul Nov 11, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

danieldk commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HuggingFaceDocBuilderDev commented Nov 10, 2026

Uh oh!

github-actions Bot commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report — kernels/

Uh oh!

drbh left a comment

Choose a reason for hiding this comment

Uh oh!

sayakpaul Nov 11, 2026

Choose a reason for hiding this comment

Uh oh!

danieldk Nov 11, 2026

Choose a reason for hiding this comment

Uh oh!

sayakpaul Nov 11, 2026

Choose a reason for hiding this comment

Uh oh!

sayakpaul Nov 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

danieldk commented Nov 10, 2026 •

edited

Loading

github-actions Bot commented Nov 10, 2026 •

edited

Loading

Coverage report — `kernels/`