popcorn 0.1.0

Documentation  |  Kernel Explorer

About

Popcorn 🍿 is a development and dispatch library for high-performance machine learning kernels. It unifies 96 kernels and more than 100 optimized implementations behind a single API, then selects among eligible backends using hardware-specific benchmark records. Each implementation is checked against a PyTorch reference; failed and unmeasured cases remain visible evidence rather than being presented as successful validation. Popcorn also ships a growing collection of first-party kernels, along with the environment and harness to build, test, benchmark, and deploy new kernels and backends. Contributions are welcome.

Installation

Install Popcorn from PyPI using uv:

uv pip install popcorn           # first-party only
uv pip install "popcorn[liger]"  # + Liger-Kernel backends
uv pip install "popcorn[fla]"    # + FLA backends

[!NOTE] Add --torch-backend=auto to let uv select a PyTorch build for your hardware.

[!WARNING] pip install popcorn may work but is not generally supported. Install the desired PyTorch build for your hardware first, then install Popcorn with pip.

Add one extra per backend you want. There is no "everything" extra: the backends pin mutually exclusive requirements, so installing them together does not resolve.

Installing also fetches the benchmark cache that dispatch selects implementations with, from the popcorn-reports dataset at the revision this version pins. Set POPCORN_SKIP_REPORTS=1 to install without it; popcorn then falls back to the reference for every call and says so. Refresh it at any time with:

uv run python -m popcorn.bench pull

A backend is eligible only when its package is installed at a declared supported version: auto-dispatch skips unavailable ones, and forcing one raises with the install hint or version error. First-party kernels (the popcorn backend) are always included.

Benchmarking on your own hardware

The shipped cache covers the hardware it was recorded on. To measure the combinations your machine has no timing for and add them to your local cache:

uv run python -m popcorn.bench fill            # every op; --limit N to subsample large grids

Already-cached combinations are skipped; pass --force to re-measure them. Dispatch picks these up on the next call.

Installing Backends

To install the prerequisites for an additional backend:

uv pip install "popcorn[<new_extra>]"

Updating

Upgrade Popcorn and refresh its pinned report cache with:

uv pip install --upgrade popcorn

Limitations

Correctness

Popcorn validates implementations across a broad grid of inputs and does its best to warn when an exact case has not been validated. This reduces the risk of numerical errors but does not guarantee correctness for every possible input. Every comparison also assumes that the registered reference is correct: Popcorn measures agreement with that reference, not correctness in the abstract, therefore "correctness" here is the measure of similarity to the reference. Validate representative production inputs, particularly unusual shapes, dtypes, and optional arguments.

Performance

Popcorn benchmarks kernels in isolation. This is useful for comparing implementations in an apples-to-apples fashion, but these results do not necessarily predict end-to-end model performance. PyTorch and torch.compile may fuse or rewrite surrounding native operations, while a backend call or custom-op boundary can limit those optimizations. Tensor layouts, memory traffic, synchronization, and compilation overhead can also change the result in a real workload. It's important to keep in mind that dispatch currently optimizes recorded execution time, not peak memory. For some workloads, we may prefer a slower implementation with a smaller memory footprint. Benchmark representative model code and explicitly tune or select a backend when latency and memory requirements are both important.

Contributing

New kernels and backends follow a guided flow: CONTRIBUTING.md. Benchmarks come from contributors' machines; run the grid on your hardware and include its matrix rows for review. Maintainers publish accepted report evidence to the pinned dataset.

Acknowledgement

Popcorn stands on the shoulders of the open-source kernel ecosystem. The optimized backends it dispatches to are built and maintained by their authors:

• flash-linear-attention
• Liger-Kernel
• quack
• flash-attention
• Unsloth

The agent optimization loop (python -m popcorn.bench.loop) is inspired by AutoKernel's edit–evaluate–keep/revert cycle for autonomous kernel search.

Citation

@software{popcorn,
  author = {{Tilde Research}},
  title  = {Popcorn: kernel dispatch for PyTorch},
  url    = {https://github.com/tilde-research/popcorn},
  year   = {2026}
}

License

Apache-2.0.