The maintainer directs new users to nanochat
nanoGPT's README opens with a November 2025 deprecation notice and points readers to nanochat. Take that notice seriously before following the older introduction, which still describes active development. This repository trains text generators and adapts GPT-2 checkpoints. I'd choose it today when the goal is understanding the training code closely enough to change it, and choose nanochat first when starting a new conversational-model project.
Our checkout contained 26 files and about 1,235 lines of source, occupying 0.6 MB. That small surface is the attraction: you can follow the model definition in model.py, then see how train.py feeds it batches and updates its weights. A larger framework can hide those connections behind abstractions. Here, changing the learning rate or checkpoint behavior means finding the code that does the work.
What happened when we ran it
Our run installed nanoGPT commit 3adf61e in 9 seconds and completed the build step in 2 seconds. We measured it on October 12, 2026, in an unprivileged Debian container with 3 CPUs and 8 GB of RAM, using the uv Python 3.12 Bookworm image. The container had no secrets. These are repository setup results, with no training throughput or model-quality measurement attached.
Installation added 35 packages and occupied 38 MB on disk. Pip-audit reported 0 known vulnerabilities in that environment. Tests were skipped because there was no test script or target. The repository scan found 0 CI workflow files, no Dockerfile, and no tests directory. A successful build step therefore gives you much less assurance than a passing behavioral suite would, especially if you intend to change the optimizer or resume logic.
Prepare the data before launching the trainer
The character-level Shakespeare example starts with python data/shakespeare_char/prepare.py. That script downloads text when needed, builds character mappings, and writes train.bin, val.bin, and meta.pkl. Training then reads the binary files. This is an approachable first path because the preparation code shows how text becomes integers, but you still need to keep the data and its encoding information with your experiment.
The 38 MB measured installation isn't a storage budget for a trained model. Training writes checkpoints into the configured output directory, and the examples fetch text or pretrained weights separately. The source disables Weights & Biases logging by default, so the basic local exercise doesn't need a hosted logging credential. Enable that integration only if you want it, and configure its account separately from dataset preparation.
CPU users must override the CUDA defaults
The trainer defaults to CUDA with compilation enabled. For its smaller CPU example, the README explicitly supplies --device=cpu --compile=False and reduces the model and batch settings. Apple Silicon users get a separate mps device suggestion. Hardware choice reaches into the command you run, so copying a GPU example onto a laptop is a poor starting point even though the Python environment installs successfully.
Our 3-CPU, 8-GB sandbox establishes that the supplied setup and build steps completed on that Debian environment. It doesn't establish that the default training configuration fits that machine, or validate the README's training-time claims. If you're learning, use the documented small configuration and inspect the checkpoint output before scaling up. Match the sampling script's device and output directory to the training configuration too.
Checkpoints and Python configs remain your responsibility
The training source saves model and optimizer state, model arguments, and experiment configuration. Resume mode reconstructs the model using the stored architecture, while the configurator executes Python files to override settings. That makes experiments easy to edit. It also makes configuration executable code you should review, and it leaves you responsible for checking whether a resumed experiment preserves the behavior you care about.
The 35-package environment came without a runnable test target in our lab. That matters for changes to this small training loop: open pull request 758 proposes saving and restoring gradient-scaler state for FP16 resume. It's a contributor's proposed fix, not an upstream guarantee or a failure reproduced in our sandbox. Teams that depend on reproducible recovery should inspect the checkpoint-resume proposal before adopting this trainer unchanged.
Sampling has a reported zero-temperature failure
Open issue 738 reports a crash when GPT.generate() receives a zero temperature. The current source divides the output scores by temperature before sampling, with no zero-temperature branch. That's a specific reason to avoid assuming that every familiar generation setting has the same meaning here as in a packaged inference library. The report concerns nanoGPT's generator, and remains separate from our setup measurements.
A 2-second successful build cannot settle that sampling behavior. Read the zero-temperature report if deterministic decoding matters to your experiment, and verify your chosen sampling path before collecting results. Pretrained imports are also explicitly limited to the GPT-2 family in model.py. Developers who need a wider model catalog should start with Transformers rather than expect nanoGPT to load an arbitrary current checkpoint.
Recent contributions don't reverse the deprecation notice
The last push was November 12, 2025. GitHub returned 63,843 stars and 352 open issues and PRs, including an October 2026 proposal to repair a dataset documentation link. GitHub's latest-release endpoint returned no release. Contributor reports and proposed fixes show continued interest, but they don't supersede the maintainer's instruction to look at nanochat. Use nanoGPT when you specifically want this inspectable trainer and can own the checks around your changes.