nndl-practice: the PyTorch companion code for Neural Networks and Deep Learning, 2nd edition

What nndl-practice is for, and who it is not for

This repository is the code half of a Chinese textbook. The README describes the book as putting model, principle and engineering practice on one line of study: you read about a component, implement it yourself in PyTorch, then use it in a runnable case. Ten chapters cover tensors and autograd, linear models, feedforward networks, convolutional networks, recurrent networks, optimization and regularization, attention and the Transformer, graph neural networks, and finally large language models with agents.

The stated audience is students and engineers with Python basics who want hands-on deep learning, optionally alongside the theory book. That framing matters, because the repository is not a package you install and call. There is no published wheel, no version tag for the code, and the README points readers at chapter directories rather than an API. If you want a maintained library that gives you a Transformer block in one import, this is the wrong shape of project. If you want to see how the block is built, it is the right one.

The README also states the second edition is in pre-publication preparation, and that both the PDF and the companion code will keep being revised before publication. Treat the current state as a working draft with tests, not as a frozen edition.

How the notebooks and the nndl framework fit together

The pedagogical mechanism is deliberate duplication followed by reuse. When a key component appears for the first time, the notebook shows the complete implementation inline. Later chapters import the engineered version from the nndl package instead of repeating it. The README gives the example `from nndl import ...` for that reuse.

That package grows across the book. Chapter 2 introduces `RunnerV1` for closed-form solving, evaluation, prediction and parameter saving. Chapter 3 adds `RunnerV2` for gradient training, validation evaluation and saving the best model. Chapter 4 adds `RunnerV3`, which brings in `DataLoader`, `state_dict`, decoupled metrics and training history. The operator and model layer expands from basic operators, losses and optimizers outward to CNN, RNN and attention components.

So the data flow a reader follows is: raw tensors and a `Dataset`, batched by `DataLoader`, fed through a model built from nndl operators, trained by a runner that records history and saves the best `state_dict`, then evaluated. The repository layout reflects this. The top level holds `README.md`, `_meta.yml`, `assets/`, `legacy/` and `pytorch/`. Everything current lives under `pytorch/`; `legacy/` is the archived NumPy and early-PyTorch content from the original `nndl/exercise` repository.

Installing nndl-practice and running the first notebook

The README gives a concrete quick start. The environment requirement is 64-bit Python 3.11 or newer and PyTorch 2.7 or newer. Notebooks default to CPU. Chapters 5, 6, 8, 9 and 10 contain longer training runs, and the README tells you to pick the short configurations described in each chapter before starting them.

Clone the repository and create a virtual environment:

git clone https://github.com/nndl/nndl-practice.git
cd nndl-practice
python -m venv .venv

Activate it. The README gives one command per platform:

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install the CPU build of PyTorch on Windows or Linux. The index URL is the CPU wheel channel, so this will not pull CUDA:

python -m pip install --upgrade pip
python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

macOS users and anyone with an NVIDIA GPU are told to take the command for their platform from the PyTorch install page instead. Then install the remaining dependencies and open the first notebook:

python -m pip install -r pytorch/requirements.txt
python -m jupyter notebook "pytorch/chap1实践基础/实践基础.ipynb"

Chapter 1 needs no data download, which is why it is the right first run: you should see the notebook open on tensors, broadcasting and autograd, and every cell should execute on CPU without further setup. Chapters 6 and 8 are different. The README states that you must prepare IMDB and LCQMC first, and that the commands and per-chapter cache locations are in `pytorch/README.md` under the data preparation section. That file is the authoritative source for environment details, dataset downloads and batch execution.

To check that your environment is sound before working through a chapter, run the test suite:

python -m pytest pytorch/tests/ -v

A single chapter can be run on its own, for example chapter 8:

python -m pytest pytorch/tests/test_chap8.py -v

The sanity tests are the strongest reason to trust the code

Each chapter ships a set of sanity tests. The README describes what they check: key operators, model shapes and core conclusions. That is a narrower claim than correctness of the book's arguments, and it is worth reading it that way. A test that verifies an operator's output shape or a convolution's arithmetic will catch a broken environment or a refactor that changed a signature. It will not tell you whether the training recipe in chapter 7 converges on your data.

Still, this is more than most textbook companion repositories offer. The tests give a reader a way to distinguish "my machine is wrong" from "the notebook is wrong" before spending an evening on a failed cell. The repository layout supports that workflow: `pytorch/tests/` sits beside the chapter directories, so a failure names a chapter directly.

One caveat the README raises itself. The repository and the manuscript share the same ten-chapter structure, but both are still being revised before publication, so individual code, outputs or page numbers may be out of sync for a while. When you hit a discrepancy, the README asks you to report the manuscript date, chapter, notebook name and specific cell. That request is a fair signal of the project's current state: the code and the prose are moving independently.

Where nndl-practice breaks down

The first limitation is data. Chapters 6 and 8 will not run out of the box, because they need IMDB and LCQMC prepared first. The README points to `pytorch/README.md` for the commands and cache locations but does not inline them in the top-level quick start. A reader who skips that file and jumps to chapter 6 will get a failure that looks like a code bug and is not one.

The second is compute. The README explicitly flags chapters 5, 6, 8, 9 and 10 as containing long training runs and tells you to choose the short configurations first. Notebooks default to CPU. That default is a sensible choice for a teaching repository, and it also means the later chapters are not something you casually run end to end on a laptop while reading. Chapter 10 covers nanoGPT, decoding with KV cache, LoRA, SFT, DPO, ReAct and RAG; the README does not claim any of those are trained to a useful quality in the notebook, and a reader expecting a working assistant should look elsewhere.

The third is language and licence. The book, the chapter directory names, the notebook names and the README are in Chinese. The code and the `nndl` API are in English, so an English-speaking reader can follow the implementation, but the explanatory text around it is not translated. The repository also does not state a licence. The README has a section on errata and suggestions and a section on series resources, and neither names one. Without a licence, the default terms apply, and that is a question for your own legal review rather than something this article can settle.

Finally, the PDF is a release asset, not a package. The `book-pdf` release dated 2026-06-22 carries the full book as `nndl-practice.pdf`, downloaded from the GitHub releases URL in the README. Nothing in the repository describes a versioned changelog for the PDF, so if you cite page numbers, record the download date, which is what the errata instructions ask for anyway.

How it differs from the first-edition PaddlePaddle code and the legacy exercises

The repository is explicit about its own lineage, and the alternatives are inside the same family. The second-edition PyTorch implementation under `pytorch/` is the current mainline, ten chapters. The first edition, published in 2022, is a separate repository, `nndl/practice-in-paddle`, with eight chapters in PaddlePaddle. The programming exercises from the first edition of the theory book live in `legacy/` here, built on NumPy and early PyTorch, kept as a historical archive.

The difference is not just framework. The ten-chapter PyTorch line reaches attention, graph neural networks and a GPT-style model, and it grows the `nndl` package with the `RunnerV1` to `RunnerV3` progression. The eight-chapter PaddlePaddle line stops earlier and uses a different framework's idioms. The legacy NumPy material has no `Runner` abstraction at all, because it predates that refactor.

If you are choosing between them, the practical split is this: use `pytorch/` unless you specifically need PaddlePaddle, and read `legacy/` only when you are following the first-edition exercise text. The README also notes that this repository was renamed from `nndl/exercise`, and that GitHub redirects old links automatically, so older references you find online should still resolve.

Editorial conclusion

Adopt nndl-practice if you already know Python and want to write convolutions, attention and a small GPT by hand instead of calling library layers, or if you teach a course and want a chapter-by-chapter notebook path with tests. Skip it if you need a supported library to ship a model, if you want a polished English-language textbook, or if you expect the PDF and the notebooks to match page for page. Before you rely on it, clone the repository, run python -m pytest pytorch/tests/ -v on your machine, and check the chapter 6 and chapter 8 data instructions in pytorch/README.md, because those two chapters will not run until the IMDB and LCQMC data is in place.

Frequently asked questions

Official sources

1. Issues
2. nndl/nndl-practice on GitHub
3. Project website
4. README
5. Releases