CubeCL: one Rust kernel function compiled for CUDA, Metal, WebGPU and the CPU

A language extension rather than a separate shader language

The pitch in the README is short: CubeCL is a Rust language extension, a just-in-time compiler, and a set of runtimes for writing high-performance compute kernels. You write an ordinary Rust function, mark it with `#[cube]`, and it compiles on demand to CUDA, HIP, Metal, SPIR-V, WGSL, or plain CPU SIMD.

The argument for doing it this way rather than shipping a separate shader language is the one a Rust developer already believes: a `#[cube]` function is type-checked, borrow-checked, composable and testable by the normal toolchain. The alternative, generating shader source at runtime, means your kernel is a string, and string does not catch anything at compile time.

The repository layout backs up the claim that this is a real compiler rather than a wrapper library. `crates/` holds the workspace members, `xtask/` the build automation, `cubecl-book/` the prose documentation, and `examples/` eight runnable programs covering device identity, device sharing, fused operations, GELU, normalization, summing, throughput measurement and tracing. The workspace root sets the toolchain floor, and it is a high one:

edition = "2024"
license = "MIT OR Apache-2.0"
readme = "README.md"
rust-version = "1.95"
version = "0.11.0-pre.4"

Edition 2024 with a minimum Rust of 1.95 means a recent toolchain is a hard requirement, not a suggestion.

Four axes of parallelism instead of a hardcoded warp size

This is the part of the README that actually explains the design, and it is worth reading closely, because it explains why the same kernel can be efficient on an AMD GPU and on a laptop CPU.

CubeCL describes hardware as four orthogonal axes. Vector is instruction-level parallelism, mapping to SIMD lanes. Plane is lockstep execution, mapping to a CUDA warp, a WebGPU subgroup or a Metal SIMD-group. CubeDim is concurrent units sharing memory that can synchronize, mapping to a CUDA block, a WebGPU workgroup or a Metal threadgroup. CubeCount has no execution guarantee at all, because the runtime schedules cubes as it sees fit, mapping to a CUDA grid or, on the CPU, a sequential loop.

Each runtime declares its maximum for each axis, and the README's instruction is that a good kernel reads those maxima at comptime and specializes on them rather than hardcoding them. The concrete example given is `warpSize == 32`, which the README calls a CUDA antipattern because it breaks on AMD where the warp is 64 and is meaningless on the CPU where there is no plane and `PLANE_DIM` is simply 1.

There is a second distinction the README insists on, and it is easy to miss: vectorization, CubeDim and CubeCount are values the user chooses at launch, while plane size is dictated by the runtime. That asymmetry is why autotuning has something to search over, and why the CPU is a first-class target rather than an afterthought. On CPU it is the same model with a plane of 1 and cubes scheduled one after another.

The README also concedes that optimal values differ a lot between targets: CPU benefits from wider vectorization thanks to AVX-512, while GPU gains saturate near 128 bits, the width of a global memory load.

Compile-time specialization, autotune, and tensor cores

Portability would normally cost performance, so the README spends a paragraph on what buys it back. Comptime specializes a kernel at compile time against the comptime-resolved values on those four axes. Autotune searches the configuration space on first run. Tensor core paths are selected automatically on hardware that supports them.

The autotune claim is the one to read most carefully, because search-at-first-run has a cost profile that has nothing to do with raw kernel speed. A configuration sweep has to actually run candidate configurations, which means the first invocation of a kernel is slower than steady state, and which means autotuning a large configuration space on a slow or shared device is expensive. The release notes show this is an active engineering area rather than a settled feature: v0.11.0-pre.2 includes an adaptive autotune scheduler with early elimination, autotune observability, and roofline bounds derived from work amount and per-resource thresholds.

The kernel cache appears in the same release notes, with a fix that invalidates the cache when a kernel changes. That is the kind of bug that only surfaces in someone's development loop, and it is a useful signal about the current stage of the runtime.

The release history also shows how much churn is normal here. Three pre-releases landed between 2026-07-29 and 2026-08-25, and their notes include an outright frontend rewrite to enable references, a new tiled layout, f64 support restored for CUDA, and a long tail of Metal and SPIR-V codegen fixes.

Pre-release cadence and the gap between Cargo.toml and the tags

The three most recent GitHub releases are v0.11.0-pre.1, v0.11.0-pre.2 and v0.11.0-pre.3, published on 2026-07-29, 2026-08-10 and 2026-08-25. The workspace manifest declares 0.11.0-pre.4. Those two facts sit side by side without a contradiction to resolve: the manifest on the default branch has already moved past the newest published tag, which is ordinary for a project cutting prereleases from the same branch.

What it means for an adopter is concrete. If you depend on the crates, pin an exact version rather than tracking a channel, because the notes between these prereleases include changes that a minor version bump would hide, such as the frontend rewrite and the tiled layout. Both `LICENSE-APACHE` and `LICENSE-MIT` sit in the repository root, and the manifest states `MIT OR Apache-2.0`, while GitHub's own licence field for this repository reports Apache-2.0 alone. Read the two licence files rather than the badge if you need to know which obligations apply to a derived crate.

The topic list on the repository is short and descriptive: cuda, gpgpu, gpu, jit, linalg, rust, webgpu. That is an accurate summary of a compiler that emits both shader languages and native SIMD, and it is also a reminder that this is a kernel layer, not a deep learning framework. There is no autodiff here and no module system. If you want those, the README is explicit about where to go instead.

Sitting between low-level wrappers and Burn

The README positions CubeCL by its neighbours, and that positioning is more useful than any feature list. It sits between low-level wrappers such as `wgpu` and `cudarc` on one side, and high-level frameworks such as Burn on the other, so that kernel libraries can be written once and reused across the Rust GPU ecosystem. The project's homepage field points at burn.dev, which is a good indication of where the demand comes from.

That middle position explains both the appeal and the cost. If you are building a numerical library that should run on an NVIDIA workstation card and on a browser through WebGPU, CubeCL removes the source-level fork that would otherwise double your maintenance. If you are building an application that just needs to train a model, it is the wrong altitude, because you would be reimplementing the convenience layers Burn already provides.

The `cubecl-book/` directory is where the conceptual material lives, and `PERFORMANCE.md` and `ERROR_HANDLING.md` at the repository root suggest the two questions a kernel author asks first. The README itself stops partway through the topology mapping table, so the backend-specific constants for each target are documented in the book rather than on the front page.

The examples directory doubles as the fastest orientation: `examples/throughput/` measures memory read throughput, `examples/device_identity/` explores the comptime identity of a device, and `examples/device_sharing/` covers multi-device setups.

Which backend question the README does not answer for you

Two things a would-be adopter will want are absent from the front page. The first is a per-backend support matrix. The README names CUDA, HIP, Metal, SPIR-V, WGSL and CPU SIMD as targets and links to `crates/cubecl-cuda` and `crates/cubecl-wgpu` with vendor badges, but it does not say which features are complete on which backend. The release notes hint at the answer: Metal receives repeated codegen fixes across prereleases, SPIR-V has its own feature fix, and RenderDoc is noted as optional because it does not compile on macOS.

The second is a hardware requirement list. There is no stated minimum compute capability, no minimum driver version, and no statement about which GPUs have been exercised. For a JIT that emits device code and manages its own kernel cache, that gap matters more than it would for a library that binds to a stable driver ABI.

The last push to the repository was on 2026-09-18, so the compiler is moving quickly. For a project at 0.11.0 pre-releases with a rewritten frontend in the recent history, the honest summary is that the architecture is settled and the implementation is still moving under it. Read `cubecl-book/` for the model, build one of the `examples/` against your own hardware, and treat the prerelease notes as the change log they are.

Editorial conclusion

CubeCL is worth reading if you are writing compute kernels in Rust and have been forced to choose between a CUDA extension and a WebGPU path, because the portability argument is made concretely rather than aspirationally. It is the wrong choice if you want batteries-included tensor operations, since it is deliberately a low-level programming model with no autodiff or module system of its own. The repository is pre-release software: the workspace sits at 0.11.0-pre.4 while the newest GitHub tag is v0.11.0-pre.3, and release notes show a frontend rewritten outright. Pin an exact version, read `cubecl-book/` for the concepts, and treat `examples/` as the spec you can actually run.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. tracel-ai/cubecl on GitHub