datawhalechina/deep-learning-notes: A Quarto Course That Starts at PyTorch and Ends at Diffusion

The gap these notes were written to fill

The README opens with a complaint rather than a feature list. Dive into Deep Learning is called an excellent introductory book, but its update pace has fallen behind the field: CLIP, Diffusion and vLLM arrived after the book's structure was set. The alternative, scattered online material, produces what the author describes as fragments. Study Attention one day, LoRA the next, diffusion models the day after, and no coherent picture forms.

The response is a single ordered path. It runs from PyTorch fundamentals and engineering practice, through Attention and Transformer-based models, into generative models (GANs, VAEs, diffusion), multimodal models such as CLIP, and the Hugging Face ecosystem, ending with practical notes on the workflow from data processing to training, inference and deployment. Each topic is meant to carry its core idea, its mathematical derivation, its code implementation and its common pitfalls together.

The audience is therefore narrow and specific. This is written for someone who is learning deep learning on their own and already writes Python. It is not a first course in machine learning, and the README never claims to be one. If you need the conceptual on-ramp before the PyTorch on-ramp, this is the wrong first stop.

Quarto Markdown as the build system, and what that buys you

The notes are maintained in Quarto Markdown and built into a static website. Quarto Markdown is plain text based on Markdown, which the README argues makes it well suited to version control and continuous updates. That choice is visible in the repository layout: _quarto.yml sits at the top level next to language-specific profiles such as _quarto-html.yml, _quarto-jupyter.yml, _quarto-typst-en.yml and _quarto-typst-zh.yml, with content split into en/ and zh/ directories and separate cs224n/ and cs336/ folders.

The practical consequence is that the notes are not a book with a frozen edition. A .qmd file is a source file, and the same source can render to HTML or to Typst for print. The Dockerfile confirms the build path: it starts from ghcr.io/quarto-dev/quarto:1.11.0, installs uv, creates a virtual environment with Python 3.14, and runs quarto render --profile html --no-execute. The --no-execute flag matters. The site build does not run the notebooks, so a broken code cell will not fail the publish job.

That is a real trade-off. Rendering without execution keeps CI fast and avoids needing GPUs on the build machine, but it means the published site cannot prove that any given cell still runs. The README's own caution about AI-assisted writing, that drafts were generated and then reviewed, revised and checked by the author, points at the same gap: correctness rests on human review, not on an automated test of every example.

Installing dnnlpy and running your first example

The README is explicit that the notes depend on a companion library. Many examples will not run without dnnlpy, which holds custom implementations and utility functions used across the chapters. The environment the author states everything was tested in is Python 3.14 with PyTorch 2.13, and pyproject.toml pins the wider dependency set, including torch>=2.14.0,<2.15.0 and transformers>=5.17.0,<5.18.0.

Start by installing the helper library:

uv pip install dnnlpy

If you want the version that tracks the repository rather than the published package, the README gives a direct-from-git form. Note the #subdirectory=dnnlpy fragment, which is required because the library lives in a subdirectory of the same repository:

uv pip install "git+https://github.com/jshn9515/deep-learning-notes.git#subdirectory=dnnlpy"

If you prefer notebooks to the rendered site, the README offers a conversion route. Install Quarto locally and convert a source file:

quarto convert path/to/file.qmd

After that command you get a Jupyter Notebook generated from the .qmd source. The README also points at jshn9515/dnnl-notebooks, a separate repository kept in sync with the main one, whose notebooks can be opened directly in Google Colab. GitHub Actions Artifacts are described as a backup source for the latest build outputs when that synchronization fails or is temporarily unavailable.

One warning deserves attention before you start. This project uses Transformers v5, and the README states that tutorials built on v4 may differ significantly in API, naming tokenizers and quantization configurations as examples. The migration guide linked from the README is the place to reconcile the two.

Maintenance mode, and what the mirror repository means for you

A caution block near the top of the README states that the repository is in maintenance mode and directs readers to jshn9515/deep-learning-notes for the latest updates. The last push to this repository was on 2026-09-10, and releases continue: v2026.08.24 was published on 2026-08-25, preceded by v2026.08.21-rc1 and v2026.07.21. So the project is not abandoned, but it is a fork point rather than the head of development.

For a tutorial this matters less than it would for a library. A derivation of the attention mechanism does not rot. What rots is the code around it. The dependency pins in pyproject.toml are tight, with upper bounds on nearly every package: torch, torchvision, transformers, diffusers, datasets, tokenizers, triton and xformers are all constrained to a single minor or patch range. Python itself is pinned to >=3.14,<3.15. If you are on Python 3.12, or on a PyTorch release outside that window, you will be resolving conflicts before you read a single chapter.

The honest reading is that this is a snapshot of one person's working environment, published. That is a strength for reproducibility and a limitation for anyone whose environment differs. The README does not document a supported upgrade path between dependency generations, and it does not promise one.

Where the notes stop being the right tool

Three cases argue against using this repository.

First, if you need the canonical, currently maintained version of these notes, the README itself sends you elsewhere. Working from the datawhalechina copy means you are reading a mirror whose synchronization is a manual process; the README treats the notebook mirror's sync failures as a real enough possibility that it names GitHub Actions Artifacts as a fallback. The same logic applies to the notes themselves.

Second, if you want to run the examples end to end on your own hardware, check the compute assumptions before committing. The dependency list includes triton on Linux, triton-windows on Windows, and xformers==0.0.35, which are GPU-oriented packages. The README does not state a minimum GPU or a CPU-only path, so that question is unanswered by the documentation. Treat GPU availability as an assumption you have to verify yourself.

Third, if you are looking for an introduction to machine learning as a subject, this is not it. The README frames the notes as a systematic organization of what the author learned, aimed at people already learning deep learning independently. There is no claim of editorial review by a second party. The AI-assisted writing note is unusually candid about this: drafts were LLM-generated, then reviewed and revised by the author, and the author states plainly that omissions or errors may remain.

How it differs from Dive into Deep Learning

The most useful comparison is with the book the README positions itself against. Dive into Deep Learning is a collaboratively authored textbook with a stable chapter structure and a broad contributor base. Its coverage reflects the field as it stood when each chapter was written, and the README's criticism is that this pace has fallen behind.

deep-learning-notes takes the opposite approach on every axis. It is single-author, so topic selection follows one person's learning path rather than a committee's outline, and that is exactly how CLIP, Stable Diffusion, SAM3 and vLLM-adjacent material enter the table of contents. It is maintained in Quarto Markdown and published as a website, so a correction ships as a commit rather than waiting for a print revision. And it ships a companion library, dnnlpy, which means the examples are not purely self-contained: they assume a specific package that the reader must install.

The cost of that flexibility is stability. A collaboratively reviewed textbook has many readers checking each chapter. A single-author site with AI-assisted drafting has one. The README acknowledges the exchange directly and asks for corrections through Issues and Pull Requests, listing error reports, clearer derivations, code comments, and structural suggestions as welcome contributions. For larger changes it asks you to open an Issue first so the approach can be discussed before you write code.

Licence split and what it means in practice

The repository carries two licences, and they cover different things. The notes themselves are under CC BY-NC 4.0, which permits sharing and adaptation with attribution but restricts commercial use. The dnnlpy library is under MIT, which is permissive and imposes no non-commercial condition.

That split is worth understanding before you build on either piece. Copying a chapter's explanation into a paid course, a commercial internal wiki, or a product's documentation sits on the non-commercial side of the line, while importing dnnlpy into a commercial codebase does not. The repository's LICENSE.txt and the licence field in pyproject.toml, which reads CC-BY-NC-4.0, are the authoritative statements; the GitHub licence indicator reports NOASSERTION, so read the file rather than the badge. None of this is legal advice, and if the distinction matters to your organization, the file is short enough to read in full.

Editorial conclusion

Adopt it if you already write Python and want a single path from PyTorch fundamentals through Attention, GANs, CLIP and diffusion models, with derivations and code side by side. Skip it if you need a maintained upstream, a beginner-level introduction to machine learning, or a stable API, because the README states the repository is in maintenance mode and points to jshn9515/deep-learning-notes, and dnnlpy is pinned to a narrow Python and PyTorch range. Before relying on it, open pyproject.toml and confirm that torch>=2.14.0,<2.15.0 and transformers>=5.17.0,<5.18.0 match the environment you actually run.

Frequently asked questions

Official sources

1. datawhalechina/deep-learning-notes on GitHub
2. Issues
3. Project website
4. README
5. Releases