tinygrad: For something between PyTorch and karpathy/micrograd. Maintained by tiny corp.

Homepage | Documentation | Discord

---

tinygrad is an end-to-end deep learning stack:

• Tensor library with autograd
• IR and compiler that fuse and lower kernels
• JIT + graph execution
• nn / optim / datasets for real training

It’s inspired by PyTorch (ergonomics), JAX (functional transforms and IR-based AD), and TVM (scheduling and codegen), but stays intentionally tiny and hackable.

---

Fork status

This repository is a working fork of the official tinygrad/tinygrad repo.

Current bring-up status: STATUS.md

That file is the main project readout for this fork. It tracks:

• current hardware and methodology
• what is implemented
• what is working
• what is still broken
• what has been tested and ruled out
• open investigation branches and requests for community feedback

Its current purpose is narrow:

• bring up and debug RDNA2 AMD support on macOS
• test specifically against a Radeon RX 6900 XT (gfx1030, Navi21 / Sienna Cichlid)
• preserve milestone code while the live bring-up work happens in a patched environment

This fork should be treated as reference-only unless you are intentionally following the same bring-up work.

Hardware under test

The current test path for this fork is:

• Mac mini M4
• USB4 / Thunderbolt 4
• ASM2464PD-based Ugreen NVMe enclosure
• M.2 to OCuLink adapter
• OCuLink eGPU setup
• Radeon RX 6900 XT

Methodology

This branch is being advanced by treating upstream Linux amdgpu as the ground truth for bring-up behavior:

• read the Linux amdgpu sources line-by-line
• identify one concrete semantic difference at a time
• port that narrow behavior into tinygrad's AM runtime
• test directly on hardware
• power cycle / restart between meaningful probes when required
• keep only changes that move the failure boundary in a reproducible way

This is not a speculative feature branch and it is not meant to represent polished, production-ready AMD support on macOS.

Use-at-your-own-risk

This fork is currently in use at your own risk territory.

Important caveats:

• it contains bring-up-oriented changes that are useful for investigation but not yet proven safe or complete
• it may regress, wedge hardware, require power cycles, or depend on platform-specific setup
• commits here should not be read as upstream-ready unless explicitly stated
• behavior that works on the hardware path above may not generalize to other Macs, bridges, enclosures, GPUs, or firmware combinations

If you want stable general tinygrad behavior, use the official upstream repo. If you want to study or reproduce this RDNA2-on-mac bring-up effort, this fork is the preserved code line for that work.

Modified files in this fork

Relative to upstream tinygrad, the active bring-up branch currently modifies this file set:

• README.md
• tinygrad/runtime/autogen/am/__init__.py
• tinygrad/runtime/autogen/am/v10_extra.py
• tinygrad/runtime/ops_amd.py
• tinygrad/runtime/support/am/amdev.py
• tinygrad/runtime/support/am/ip.py
• tinygrad/runtime/support/amd.py
• tinygrad/runtime/support/hcq.py

In practice, most of the RDNA2 bring-up work is concentrated in:

• tinygrad/runtime/support/am/ip.py
• tinygrad/runtime/support/am/amdev.py
• tinygrad/runtime/ops_amd.py

The other touched files are supporting surfaces needed to keep the AM path coherent on this branch.

---

How tinygrad compares

PyTorch

• ✅ Similar: eager Tensor API, autograd, optim, basic datasets and layers.
• ✅ You can write familiar training loops.
• 🔁 Unlike PyTorch, the entire compiler and IR are visible and hackable.

JAX

• ✅ IR-based autodiff over primitives (like JAXPR + XLA).
• ✅ Function-level JIT (TinyJit) that captures and replays kernels.
• 🔁 Fewer functional transforms (no full vmap/pmap yet), but far easier to read.

TVM

• ✅ Multiple lowering passes, scheduling, and BEAM search over kernels.
• ✅ Device “graphs” for batched execution.
• 🔁 tinygrad also ships the front-end framework (tensors, nn, optim), not just the compiler.

---

Laziness

Try a matmul. See how, despite the style, it is fused into one kernel with the power of laziness.

DEBUG=3 python3 -c "from tinygrad import Tensor;
N = 1024; a, b = Tensor.empty(N, N), Tensor.empty(N, N);
(a.reshape(N, 1, N) * b.T.reshape(1, N, N)).sum(axis=2).realize()"

And we can change DEBUG to 4 to see the generated code.

Neural networks

As it turns out, 90% of what you need for neural networks are a decent autograd/tensor library. Throw in an optimizer, a data loader, and some compute, and you have all you need.

from tinygrad import Tensor, nn

class LinearNet:
  def __init__(self):
    self.l1 = Tensor.kaiming_uniform(784, 128)
    self.l2 = Tensor.kaiming_uniform(128, 10)
  def __call__(self, x:Tensor) -> Tensor:
    return x.flatten(1).dot(self.l1).relu().dot(self.l2)

model = LinearNet()
optim = nn.optim.Adam([model.l1, model.l2], lr=0.001)

x, y = Tensor.rand(4, 1, 28, 28), Tensor([2,4,3,7])  # replace with real mnist dataloader

with Tensor.train():
  for i in range(10):
    optim.zero_grad()
    loss = model(x).sparse_categorical_crossentropy(y).backward()
    optim.step()
    print(i, loss.item())

See examples/beautiful_mnist.py for the full version that gets 98% in ~5 seconds

Accelerators

tinygrad already supports numerous accelerators, including:

• OpenCL
• CPU
• METAL
• CUDA
• AMD
• NV
• QCOM
• WEBGPU

And it is easy to add more! Your accelerator of choice only needs to support a total of ~25 low level ops.

To check default accelerator run: python3 -c "from tinygrad import Device; print(Device.DEFAULT)"

Installation

The current recommended way to install tinygrad is from source.

From source

git clone https://github.com/tinygrad/tinygrad.git
cd tinygrad
python3 -m pip install -e .

Direct (master)

python3 -m pip install git+https://github.com/tinygrad/tinygrad.git

Documentation

Documentation along with a quick start guide can be found on the docs website built from the docs/ directory.

Quick example comparing to PyTorch

from tinygrad import Tensor

x = Tensor.eye(3, requires_grad=True)
y = Tensor([[2.0,0,-2.0]], requires_grad=True)
z = y.matmul(x).sum()
z.backward()

print(x.grad.tolist())  # dz/dx
print(y.grad.tolist())  # dz/dy

The same thing but in PyTorch:

import torch

x = torch.eye(3, requires_grad=True)
y = torch.tensor([[2.0,0,-2.0]], requires_grad=True)
z = y.matmul(x).sum()
z.backward()

print(x.grad.tolist())  # dz/dx
print(y.grad.tolist())  # dz/dy

Contributing

There has been a lot of interest in tinygrad lately. Following these guidelines will help your PR get accepted.

We'll start with what will get your PR closed with a pointer to this section:

• No code golf! While low line count is a guiding light of this project, anything that remotely looks like code golf will be closed. The true goal is reducing complexity and increasing readability, and deleting \ns does nothing to help with that.
• All docs and whitespace changes will be closed unless you are a well-known contributor. The people writing the docs should be those who know the codebase the absolute best. People who have not demonstrated that shouldn't be messing with docs. Whitespace changes are both useless and carry a risk of introducing bugs.
• Anything you claim is a "speedup" must be benchmarked. In general, the goal is simplicity, so even if your PR makes things marginally faster, you have to consider the tradeoff with maintainability and readability.
• In general, the code outside the core tinygrad/ folder is not well tested, so unless the current code there is broken, you shouldn't be changing it.
• If your PR looks "complex", is a big diff, or adds lots of lines, it won't be reviewed or merged. Consider breaking it up into smaller PRs that are individually clear wins. A common pattern I see is prerequisite refactors before adding new functionality. If you can (cleanly) refactor to the point that the feature is a 3 line change, this is great, and something easy for us to review.

Now, what we want:

• Bug fixes (with a regression test) are great! This library isn't 1.0 yet, so if you stumble upon a bug, fix it, write a test, and submit a PR, this is valuable work.
• Solving bounties! tinygrad offers cash bounties for certain improvements to the library. All new code should be high quality and well tested.
• Features. However, if you are adding a feature, consider the line tradeoff. If it's 3 lines, there's less of a bar of usefulness it has to meet over something that's 30 or 300 lines. All features must have regression tests. In general with no other constraints, your feature's API should match torch or numpy.
• Refactors that are clear wins. In general, if your refactor isn't a clear win it will be closed. But some refactors are amazing! Think about readability in a deep core sense. A whitespace change or moving a few functions around is useless, but if you realize that two 100 line functions can actually use the same 110 line function with arguments while also improving readability, this is a big win. Refactors should pass process replay.
• Tests/fuzzers. If you can add tests that are non brittle, they are welcome. We have some fuzzers in here too, and there's a plethora of bugs that can be found with them and by improving them. Finding bugs, even writing broken tests (that should pass) with @unittest.expectedFailure is great. This is how we make progress.
• Dead code removal from core tinygrad/ folder. We don't care about the code in extra, but removing dead code from the core library is great. Less for new people to read and be confused by.

Running tests

You should install the pre-commit hooks with pre-commit install. This will run the linter, mypy, and a subset of the tests on every commit.

For more examples on how to run the full test suite please refer to the CI workflow.

Some examples of running tests locally:

python3 -m pip install -e '.[testing]'  # install extra deps for testing
python3 test/backend/test_ops.py        # just the ops tests
python3 -m pytest test/                 # whole test suite

Process replay tests

Process replay compares your PR's generated kernels against master. If your PR is a refactor or speedup without any expected behavior change, It should include [pr] in the pull request title.