# Dive into Deep Learning (Chinese Edition) — User Guide

> A reader's handbook for **动手学深度学习** (`d2l-zh`, version 2.0.0): how to install the environment, choose a deep-learning framework, run the code, and navigate the 19-chapter textbook.

## 1. Quick Start

`d2l-ai/d2l-zh` is the **simplified-Chinese edition** of the open textbook *Dive into Deep Learning* (动手学深度学习, D2L). It is authored by Aston Zhang, Zachary C. Lipton, Mu Li, and Alexander J. Smola, and is published in print by Cambridge University Press (2023). The repository pins release `2.0.0`, which corresponds to the second Chinese edition at [zh.d2l.ai](https://zh.d2l.ai).

Unlike a typical software project, the repository is itself **a book**. Every chapter is a Markdown file that is also executable as a Jupyter notebook, so every algorithm the book describes can be run, modified, and inspected. Code samples exist in four parallel framework implementations — **Apache MXNet**, **PyTorch**, **TensorFlow**, and **PaddlePaddle** — and a small helper library, `d2l`, hides the framework-specific boilerplate behind a uniform API.

### Key features

- **Four frameworks, one codebase** — each chapter renders parallel implementations selectable by tab
- **Executable textbook** — every `.md` chapter doubles as a Jupyter notebook via the `d2lbook` toolchain
- **Unified helper library** — `from d2l import torch as d2l` gives you plotting, data loading, and training utilities
- **19 chapters** covering linear networks through Transformers and BERT
- **Multi-format output** — HTML site, framework-specific PDFs, notebook ZIPs, Colab/SageMaker mirrors
- **Chinese-English parallel** — `_origin.md` files maintain translation alignment with `d2l-ai/d2l-en`

### Prerequisites

- Python 3.9 (Miniconda recommended)
- One deep-learning framework: PyTorch, TensorFlow, MXNet, or PaddlePaddle

### Fastest path to running code

```bash
conda create --name d2l python=3.9 -y
conda activate d2l
pip install torch==1.12.0 torchvision==0.13.0
pip install d2l==0.17.6
mkdir d2l-zh && cd d2l-zh
curl https://zh-v2.d2l.ai/d2l-zh-2.0.0.zip -o d2l-zh.zip
unzip d2l-zh.zip && rm d2l-zh.zip
cd pytorch
jupyter notebook
```

Expected output:

```text
[I 10:32:14.812 NotebookApp] Serving notebooks from local directory: /.../d2l-zh/pytorch
[I 10:32:14.812 NotebookApp] Jupyter Notebook is running at:
[I 10:32:14.812 NotebookApp] http://localhost:8888/?token=...
```

Open `chapter_preliminaries/ndarray.ipynb` and press **Shift + Enter** to execute the first code cell. If tensors print without errors, the environment is ready.

> [!TIP]
> If you just want to **read** without installing anything, visit [zh.d2l.ai](https://zh.d2l.ai). Come back to this guide when you want to **run** the code. Google Colab mirrors are also available for each framework — no local setup needed.

### What to try next

- See §2 for full installation instructions across all platforms and frameworks.
- See §4 for how to use the `d2l` helper library in your own notebooks.
- See §5 for suggested reading paths and common tasks.

---

## 2. Installation

The repository's `chapter_installation/index.md` is the canonical install guide; what follows is a condensed, platform-by-platform distillation.

### 2.1 System requirements

The `setup.py` file declares the `d2l` helper library works on Python 3.5 or newer, but the rest of the book's code targets modern Python. Use **Python 3.9**.

| Resource | Minimum | Recommended |
|---|---|---|
| Python | 3.7 | 3.9 |
| RAM | 4 GB | 16 GB |
| Disk | 5 GB for code + datasets | 20 GB |
| GPU | Not required for chapters 1-7 | NVIDIA with CUDA for chapters 8-15 |
| OS | macOS 10.14+, Ubuntu 18.04+, Windows 10+ | Ubuntu 22.04 + CUDA 11+ |

> [!IMPORTANT]
> The CV and NLP chapters (`chapter_computer-vision/`, `chapter_natural-language-processing-*/`) fine-tune networks on real datasets. On CPU, a single epoch of ResNet-18 on CIFAR-10 can take over an hour. Secure a GPU before reaching chapter 7 (Modern CNNs) if you plan to run everything yourself.

### 2.2 Install Miniconda

The book standardizes on Conda-managed Python.

=== "macOS"

    ```bash
    # For Intel Macs (Apple Silicon users: download the arm64 installer instead)
    sh Miniconda3-py39_4.12.0-MacOSX-x86_64.sh -b
    ~/miniconda3/bin/conda init
    ```

=== "Linux"

    ```bash
    sh Miniconda3-py39_4.12.0-Linux-x86_64.sh -b
    ~/miniconda3/bin/conda init
    ```

=== "Windows"

    Download the `.exe` installer from [conda.io/en/latest/miniconda.html](https://conda.io/en/latest/miniconda.html) and run it. Open the **Anaconda Prompt** afterwards; `conda` is available there without `PATH` changes.

Close and reopen the shell, then create the `d2l` environment:

```bash
conda create --name d2l python=3.9 -y
conda activate d2l
```

### 2.3 Install a deep-learning framework

The book supports four frameworks. Pick one; you do not need all four. The **PyTorch** tab is the most actively discussed in the community.

=== "PyTorch"

    ```bash
    pip install torch==1.12.0
    pip install torchvision==0.13.0
    ```

=== "TensorFlow"

    ```bash
    pip install tensorflow==2.8.0
    pip install tensorflow-probability==0.16.0
    ```

=== "MXNet"

    ```bash
    # CPU-only
    pip install mxnet==1.7.0.post1

    # CUDA 10.1 (Linux/macOS)
    pip install mxnet-cu101==1.7.0

    # CUDA 10.1 on Windows
    pip install mxnet-cu101==1.7.0 -f https://dist.mxnet.io/python
    ```

=== "PaddlePaddle"

    ```bash
    # CPU-only (using the Tsinghua mirror, fast inside mainland China)
    python -m pip install paddlepaddle==2.3.2 -i https://pypi.tuna.tsinghua.edu.cn/simple

    # CUDA 11.2
    python -m pip install paddlepaddle-gpu==2.3.2.post112 \
      -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html
    ```

> [!WARNING]
> Apache MXNet's upstream maintenance has wound down. The pinned `mxnet==1.7.0` is an older release; newer OS + driver combinations may fail to install. If you are starting fresh and have no other constraint, choose PyTorch or PaddlePaddle instead.

### 2.4 Install the `d2l` helper library

```bash
pip install d2l==0.17.6
```

> [!IMPORTANT]
> The version `0.17.6` published to PyPI is the one the `chapter_installation` page of the book pins. The helper library is framework-agnostic — it imports only `jupyter`, `numpy`, `matplotlib`, `requests`, and `pandas` — and delegates tensor operations to whichever framework you already installed.

### 2.5 Download the notebooks

The book's source Markdown is converted to Jupyter notebooks by the `d2lbook` toolchain. The ready-made ZIP contains those notebooks already built, one subdirectory per framework.

=== "PyTorch"

    ```bash
    mkdir d2l-zh && cd d2l-zh
    curl https://zh-v2.d2l.ai/d2l-zh-2.0.0.zip -o d2l-zh.zip
    unzip d2l-zh.zip && rm d2l-zh.zip
    cd pytorch
    ```

=== "TensorFlow"

    ```bash
    mkdir d2l-zh && cd d2l-zh
    curl https://zh-v2.d2l.ai/d2l-zh-2.0.0.zip -o d2l-zh.zip
    unzip d2l-zh.zip && rm d2l-zh.zip
    cd tensorflow
    ```

=== "MXNet"

    ```bash
    mkdir d2l-zh && cd d2l-zh
    curl https://zh-v2.d2l.ai/d2l-zh-2.0.0.zip -o d2l-zh.zip
    unzip d2l-zh.zip && rm d2l-zh.zip
    cd mxnet
    ```

=== "PaddlePaddle"

    ```bash
    mkdir d2l-zh && cd d2l-zh
    curl https://zh-v2.d2l.ai/d2l-zh-2.0.0.zip -o d2l-zh.zip
    unzip d2l-zh.zip && rm d2l-zh.zip
    cd paddle
    ```

If `unzip` is missing on Debian/Ubuntu, install it first:

```bash
sudo apt install unzip
```

### 2.6 Verify the install

```bash
conda activate d2l
python -c "import d2l; print(d2l.__version__)"
```

Expected output:

```text
0.17.6
```

Then, to confirm your chosen framework works end to end:

```python
from d2l import torch as d2l         # or: from d2l import mxnet as d2l
x = d2l.tensor([1.0, 2.0, 3.0])
print(x)
```

If the line prints a tensor object, you are done.

- [x] Conda environment `d2l` created with Python 3.9.
- [x] One of `torch` / `tensorflow` / `mxnet` / `paddlepaddle` installed.
- [x] `d2l==0.17.6` installed.
- [x] Notebooks downloaded and unzipped.
- [x] `python -c "import d2l"` succeeds.

---

## 3. Configuration

### 3.1 Choosing a framework

The book supports four frameworks because each has pedagogical strengths. For a new reader:

| Framework | When to choose | Watch-outs |
|---|---|---|
| **PyTorch** | Default for most readers. Largest discussion activity, strongest research ecosystem. | Some MXNet-era tricks (lazy init, hybrid blocks) are simulated, not native. |
| **TensorFlow** | If your workplace or course already uses it. | TF 2.x still carries some Graph/Eager duality; the book uses Eager mode. |
| **PaddlePaddle** | Strong for readers in mainland China; good Chinese-language support. | Smaller community outside China. |
| **MXNet** | Historical: the original book was written against MXNet/Gluon. | Maintenance has wound down; the pinned release is old. |

You can **switch frameworks mid-book** by redownloading the ZIP and extracting a different subdirectory, but your prior notebook outputs will not transfer. The surrounding prose — the *book* — does not change.

> [!TIP]
> If you are preparing a class, standardize on one framework for the cohort. The tabbed code is designed for parity, but students comparing notes across frameworks can still run into minor numerical differences (different RNG seeds, different dropout implementations).

### 3.2 The `d2l` import convention

The import convention is identical across frameworks, thanks to the `d2l` package's aliasing layer:

```python
# Choose exactly one
from d2l import mxnet as d2l        # MXNet backend
from d2l import torch as d2l        # PyTorch backend
from d2l import tensorflow as d2l   # TensorFlow backend
from d2l import paddle as d2l       # PaddlePaddle backend
```

The **same call names** work under all four backends — under the hood, the build system rewrites them into native framework operations using the alias maps declared in `config.ini`. For example, `d2l.matmul(X, w)` becomes `np.dot(X, w)` in the MXNet build, `torch.matmul(X, w)` in the PyTorch build, and `tf.matmul(X, w)` in the TensorFlow build.

### 3.3 Dataset caching

The `d2l` helper library downloads datasets on demand and caches them under `~/.d2l/`. For example, `d2l.load_data_fashion_mnist(batch_size=256)` fetches Fashion-MNIST from `http://d2l-data.s3-accelerate.amazonaws.com/` the first time it is called. Subsequent calls read from the cache.

If your network blocks S3, download the dataset ZIPs once by hand and place them under `~/.d2l/` before running the notebook. The URL and expected SHA-1 hash appear in the `d2l/<framework>.py` file's `DATA_HUB` dictionary.

> [!NOTE]
> Inside mainland China, mirror services and Kaggle-hosted copies of Fashion-MNIST, CIFAR-10, and the time-machine text sometimes load faster than S3. Pre-warm the cache before a long study session.

### 3.4 Distribution formats

The same source repository is rendered into four consumable formats:

| Format | URL / File | Best for |
|---|---|---|
| Online HTML | [zh.d2l.ai](https://zh.d2l.ai) | Casual reading, anchor links, forum discussion threads |
| PDF — MXNet variant | `https://zh-v2.d2l.ai/d2l-zh.pdf` | Offline reading, print |
| PDF — PyTorch variant | `https://zh-v2.d2l.ai/d2l-zh-pytorch.pdf` | Offline reading, print |
| Notebook ZIP | `https://zh-v2.d2l.ai/d2l-zh-2.0.0.zip` | Running code locally |
| Google Colab | `d2l-ai/d2l-zh-colab`, `d2l-ai/d2l-zh-pytorch-colab`, `d2l-ai/d2l-zh-tensorflow-colab`, `d2l-ai/d2l-zh-paddle-colab` | Running code without a local install |
| AWS SageMaker | `d2l-ai/d2l-zh-sagemaker` (and per-framework siblings) | Managed notebooks with GPUs |

For full configuration reference (build config, alias system, CI settings), see the **Admin Guide**.

---

## 4. Core Usage

### 4.1 Repository structure at a glance

| Artifact | Where | Purpose |
|---|---|---|
| Chapter source | `chapter_*/*.md` | Chinese Markdown + executable code cells |
| English originals | `chapter_*/*_origin.md` | Source English paragraphs used for translation sync |
| Helper library | `d2l/` | `d2l.py` backends: `mxnet.py`, `torch.py`, `tensorflow.py`, `paddle.py` |
| Figures | `img/*.svg`, `img/*.png` | Pre-rendered diagrams and photographs |
| Figure sources | `graffle/**/*.graffle` | OmniGraffle originals (macOS) |
| Build config | `config.ini` | `d2lbook` project definition |
| Install recipe | `setup.py` | Metadata for the `d2l` PyPI package |
| Post-processing | `static/post_latex/main.py` | Cleans generated LaTeX before PDF output |
| CI | `ci/` | AWS Batch submission script + per-framework Dockerfiles |
| Contrib | `contrib/` | Draft chapters not yet promoted into the main book |
| Style | `STYLE_GUIDE.md`, `TERMINOLOGY.md` | Formatting rules and the Chinese-English glossary |

> [!NOTE]
> The Markdown files in `chapter_*/` are not ordinary prose. They contain `:label:`, `:eqlabel:`, `:numref:`, and `:begin_tab:` / `:end_tab:` directives from the [`d2lbook`](https://book.d2l.ai) toolchain, plus `#@tab <framework>` annotations that select which code variant runs for a given build.

### 4.2 Launch Jupyter

From the framework subdirectory of the unzipped notebooks:

```bash
jupyter notebook
```

Jupyter prints a URL like `http://localhost:8888/?token=...` and opens the browser automatically. On a headless server, open that URL manually in a local browser or add `--ip=0.0.0.0 --no-browser` and tunnel over SSH.

> [!IMPORTANT]
> Re-run `conda activate d2l` in every new terminal session before launching Jupyter. Without it, the wrong Python interpreter will be used and imports will fail with `ModuleNotFoundError: No module named 'd2l'`.

### 4.3 Run a cell

Click any code cell and press **Shift + Enter**. The cell executes; the output appears beneath. A `*` in the brackets (`In [*]`) means the cell is still running.

### 4.4 The `d2l` helper library

After the import you have access to a **shared vocabulary** of utility functions and classes:

| Call | Purpose |
|---|---|
| `d2l.plot(X, Y, xlabel=..., ylabel=...)` | Quickly plot one or more curves |
| `d2l.Timer()` | Measure elapsed time |
| `d2l.Accumulator(n)` | Running sums across minibatches |
| `d2l.Animator(...)` | Live-updating loss/accuracy plot in a notebook |
| `d2l.load_data_fashion_mnist(batch_size)` | Return train/test `DataLoader`s for Fashion-MNIST |
| `d2l.train_epoch_ch3(net, train_iter, loss, updater)` | One training epoch, chapter-3 style |
| `d2l.evaluate_accuracy(net, data_iter)` | Classification accuracy |
| `d2l.get_fashion_mnist_labels(y)` | Map label index → class name |
| `d2l.synthetic_data(w, b, n)` | Generate `n` points for `y = Xw + b + noise` |
| `d2l.linreg(X, w, b)` / `d2l.squared_loss(y_hat, y)` / `d2l.sgd(...)` | Chapter-3 linear-regression building blocks |

> [!NOTE]
> The `d2l` package's source of truth lives in `d2l/<framework>.py`. Those files are auto-generated by the book's build pipeline from the chapters themselves — every function marked `#@save` in a chapter is extracted into the library. This is why reading a chapter is enough to understand where a helper came from.

### 4.5 Switch between code tabs inside a chapter

Each chapter's source `.md` contains blocks wrapped in `:begin_tab:<framework>` / `:end_tab:` directives. The pre-built notebooks contain **only** the cells for the framework variant you unzipped. To see the alternative implementation of a given algorithm, open `chapter_*/xxx_origin.md` (the English source) and search for the `:begin_tab:` blocks, or visit the corresponding section on [zh.d2l.ai](https://zh.d2l.ai) and use the framework-switch button in the navbar.

### 4.6 Hardware guidance

| Point in the book | CPU viable? | Notes |
|---|---|---|
| `chapter_preliminaries/` through `chapter_multilayer-perceptrons/` | Yes | Problems fit in milliseconds to seconds |
| `chapter_convolutional-neural-networks/` (LeNet on MNIST) | Yes, but slow | ~2-3 min/epoch on CPU |
| `chapter_convolutional-modern/` (AlexNet, VGG, ResNet on ImageNet/CIFAR) | No | Each epoch may exceed an hour |
| `chapter_recurrent-modern/`, `chapter_attention-mechanisms/` (translation tasks) | No | Dense matmuls dominate; GPU mandatory |
| `chapter_computer-vision/` (object detection, fine-tuning) | No | Pre-trained backbones + large data |
| `chapter_natural-language-processing-pretraining/` (BERT) | No | GPU essential |

Cloud options the book documents:

- **AWS EC2** — `chapter_appendix-tools-for-deep-learning/aws.md` walks through launching a Deep Learning AMI instance.
- **AWS SageMaker** — `chapter_appendix-tools-for-deep-learning/sagemaker.md` covers creating a notebook instance.
- **Google Colab** — the book's per-framework Colab mirrors host ready-to-run notebooks with free GPU/TPU tiers.
- **Server + GPU selection** — `chapter_appendix-tools-for-deep-learning/selecting-servers-gpus.md` compares T4 / V100 / A100 class hardware.

> [!TIP]
> For the Kaggle competitions inside `chapter_computer-vision/kaggle-cifar10.md` and `kaggle-dog.md`, Kaggle's own hosted kernels (free GPU, dataset pre-mounted) are often the simplest option.

### 4.7 Cleanly stop your session

Stop the Jupyter server with **Ctrl + C** in the terminal where you launched it. Then:

```bash
conda deactivate
```

---

## 5. Common Tasks

### 5.1 The book's structure

The book is organized in three macro-parts.

**Part I — Foundations (chapters 1-4)**

| Chapter folder | Coverage |
|---|---|
| `chapter_preface` | Author intent, how to read the book |
| `chapter_installation` | Environment setup (the one mirrored in §2 above) |
| `chapter_notation` | Math notation, typographic conventions |
| `chapter_introduction` | What machine learning is, key paradigms (supervised, self-supervised, RL), a historical tour |
| `chapter_preliminaries` | Data structures (`ndarray`), linear algebra, calculus, automatic differentiation, probability, pandas, documentation lookup |

**Part II — Modern Deep Learning (chapters 5-11)**

| Chapter folder | Coverage |
|---|---|
| `chapter_linear-networks` | Linear regression, softmax regression; "from scratch" and "concise" pairs |
| `chapter_multilayer-perceptrons` | MLPs, backpropagation, weight decay, dropout, numerical stability, Kaggle house-price case study |
| `chapter_deep-learning-computation` | Layer/block abstractions, parameter management, deferred init, custom layers, file I/O, GPU tensors |
| `chapter_convolutional-neural-networks` | Correlation, padding, strides, pooling, channels, LeNet |
| `chapter_convolutional-modern` | AlexNet, VGG, NiN, GoogLeNet, batch normalization, ResNet, DenseNet |
| `chapter_recurrent-neural-networks` | Sequence models, text preprocessing, language modeling, RNN from scratch and concise, BPTT |
| `chapter_recurrent-modern` | GRU, LSTM, deep RNN, bidirectional RNN, encoder-decoder, seq2seq, beam search, machine translation |
| `chapter_attention-mechanisms` | Attention cues, Nadaraya-Watson, scoring functions, Bahdanau attention, multi-head, self-attention, positional encoding, Transformer |

**Part III — Advanced Topics and Applications (chapters 12-15)**

| Chapter folder | Coverage |
|---|---|
| `chapter_optimization` | Convexity, gradient descent, SGD, momentum, Adagrad, RMSProp, Adadelta, Adam, LR scheduling |
| `chapter_computational-performance` | Compiler tricks, asynchronous compute, auto-parallelism, hardware overview, multi-GPU training, parameter servers |
| `chapter_computer-vision` | Image augmentation, fine-tuning, bounding boxes, anchors, SSD, R-CNN family, semantic segmentation, FCN, transposed convolutions, style transfer, CIFAR-10 and Kaggle dog-breed cases |
| `chapter_natural-language-processing-pretraining` | word2vec, negative sampling, hierarchical softmax, GloVe, fastText, subword embeddings, pre-training BERT |
| `chapter_natural-language-processing-applications` | Sentiment analysis (RNN & CNN), natural language inference, fine-tuning BERT |

**Appendix**

| Chapter folder | Coverage |
|---|---|
| `chapter_appendix-tools-for-deep-learning` | Jupyter usage tips, deploying on AWS, SageMaker, GPU/server selection, how to contribute, reference for the `d2l` API |
| `chapter_references` | Bibliography (also present as `d2l.bib` at the repo root) |

**The `contrib/` folder**

`contrib/chapter_recommender-systems/` contains draft material on recommender systems (AutoRec, factorization machines, matrix factorization, MovieLens, CTR prediction) that is not yet part of the main book. `contrib/to-rm-mx-contrib-text/` is a retired MXNet-era NLP chapter kept for archival.

> [!CAUTION]
> Contents under `contrib/` are excluded from the website build (see `config.ini` exclusions). They may be out of date or incomplete.

### 5.2 Suggested reading paths

**Complete traversal (≈ one semester):** Read straight through from `chapter_preface` to `chapter_natural-language-processing-applications`. Run every notebook; skip no exercises. Expect 12-16 weeks.

**"Skip the math" fast path (≈ four weeks):**

1. `chapter_introduction/index.md` — motivation
2. `chapter_preliminaries/ndarray.md` + `autograd.md` — tensor & autograd mechanics
3. `chapter_linear-networks/linear-regression-concise.md` — the shortest working training loop
4. `chapter_multilayer-perceptrons/mlp-concise.md` — nonlinearity
5. `chapter_convolutional-neural-networks/lenet.md` — the first real CNN
6. `chapter_convolutional-modern/resnet.md` — the workhorse architecture
7. `chapter_recurrent-modern/seq2seq.md` — sequence generation
8. `chapter_attention-mechanisms/transformer.md` — the Transformer

Skipping the *from-scratch* sections halves the time but hides how the abstractions work. Return to them later.

**NLP-focused path:** `chapter_preliminaries/` → `chapter_linear-networks/` → `chapter_multilayer-perceptrons/` → `chapter_recurrent-neural-networks/` → `chapter_recurrent-modern/` → `chapter_attention-mechanisms/` → `chapter_natural-language-processing-pretraining/` → `chapter_natural-language-processing-applications/`.

**Computer-vision-focused path:** `chapter_preliminaries/` → `chapter_linear-networks/` → `chapter_multilayer-perceptrons/` → `chapter_deep-learning-computation/` → `chapter_convolutional-neural-networks/` → `chapter_convolutional-modern/` → `chapter_computer-vision/`.

### 5.3 Run a single notebook from the command line

```bash
conda activate d2l
jupyter nbconvert --to notebook --execute \
  chapter_linear-networks/linear-regression-concise.ipynb \
  --output executed_linear-regression-concise.ipynb
```

Expected output:

```text
[NbConvertApp] Converting notebook chapter_linear-networks/linear-regression-concise.ipynb to notebook
[NbConvertApp] Writing 124578 bytes to chapter_linear-networks/executed_linear-regression-concise.ipynb
```

### 5.4 Convert the book's Markdown to a notebook yourself

The release ZIP already contains `.ipynb` files. If you prefer to work from the raw Markdown chapters in `chapter_*/*.md`, the `d2lbook` toolchain converts them:

```bash
pip install d2lbook
d2lbook build eval
```

This produces notebooks under `_build/eval/`. Each `.md` becomes one `.ipynb`; the `#@tab <framework>` annotations select which code cells survive.

> [!NOTE]
> `d2lbook` is the build tool used internally by the authors. Most readers do not need it — the pre-built notebook ZIP is the official distribution channel. Building locally is only interesting if you want to modify content and re-render the output.

### 5.5 Print a quick plot with the book's helper

```python
from d2l import torch as d2l
import torch

x = torch.arange(-5, 5, 0.1)
d2l.plot(x, [torch.sin(x), torch.cos(x)], 'x', 'f(x)', legend=['sin', 'cos'])
```

This produces an SVG plot directly inside the notebook. `d2l.plot` auto-sets `figsize`, the `matplotlib` SVG backend, and axis grids to the book's style.

### 5.6 Join the discussion forum

Each section of the book ends with a link like `[Discussions](https://discuss.d2l.ai/t/2082)`. Those numeric IDs point to a dedicated forum thread for that section. If something is unclear, post there; the authors and veteran readers respond.

### 5.7 Glossary (key terms)

The full English↔Chinese glossary lives in `TERMINOLOGY.md`. Key terms the book uses consistently:

| 中文 | English | Notes |
|---|---|---|
| 标签 | label | Target variable |
| 步幅 | stride | CNN parameter |
| 参数 | parameter | Learned weights |
| 超参数 | hyperparameter | Set before training |
| 词元 | token | Output of the tokenizer |
| 词嵌入 | word embedding | Vector representation of a word |
| 层 | layer | A single neural-network block |
| 暂退法 | dropout | Regularization by masking |
| 多层感知机 | multilayer perceptron (MLP) | Fully connected network |
| 多头注意力 | multi-head attention | Transformer primitive |
| 泛化 | generalization | Model behavior on unseen data |
| 小批量随机梯度下降 | minibatch stochastic gradient descent | The default optimizer |
| 长短期记忆网络 | long short-term memory (LSTM) | Gated RNN |
| 注意力 | attention | Weighted context aggregation |
| 归一化 | normalization | Scaling features or activations |

See `TERMINOLOGY.md` for the complete list (100+ entries).

---

## 6. Troubleshooting

### Error: `ModuleNotFoundError: No module named 'd2l'`

**Cause:** the `d2l` environment is not active, or `d2l==0.17.6` was installed into a different environment.

**Solution:**

```bash
conda activate d2l
pip show d2l | grep Version
```

Expected output:

```text
Version: 0.17.6
```

If the version differs, reinstall: `pip install --force-reinstall d2l==0.17.6`.

**Prevention:** always open a fresh terminal, run `conda activate d2l`, *then* launch Jupyter.

### Error: `No module named 'mxnet'` / `'torch'` / `'tensorflow'` / `'paddle'`

**Cause:** the framework that matches the subdirectory you unzipped (`mxnet/`, `pytorch/`, `tensorflow/`, or `paddle/`) is not installed in the active environment.

**Solution:** install the framework listed at the top of the failing notebook (see §2.3) *in the same environment* where `d2l` lives.

**Prevention:** decide on a framework first, install exactly that one, then `cd` into the matching subdirectory.

### Error: `AssertionError: Torch not compiled with CUDA enabled` when calling `try_gpu()`

**Cause:** PyTorch was installed from the default PyPI wheel without CUDA, but the notebook is trying to move a tensor to GPU.

**Solution:** either install a CUDA-enabled PyTorch wheel from [pytorch.org/get-started/locally](https://pytorch.org/get-started/locally) that matches your CUDA driver, or force the code onto CPU by calling `device = d2l.try_gpu()` which falls back to `cpu()` when CUDA is unavailable. On CPU the run will be slow but correct.

**Prevention:** before installing a framework, check your CUDA driver: `nvcc --version`. Install the matching wheel.

> [!WARNING]
> CUDA version mismatches between the driver and the PyTorch wheel are the single most common installation failure. Always verify `nvidia-smi` (driver CUDA) and `nvcc --version` (toolkit CUDA) show compatible versions before installing a GPU wheel.

### Error: `CUDA out of memory` during training

**Cause:** the batch size in the notebook exceeds what your GPU can hold.

**Solution:**

```python
# Typical book default
batch_size = 256

# Halve until it fits
batch_size = 128
```

Also close other notebooks that hold GPU tensors.

**Prevention:** monitor GPU usage with `nvidia-smi` before starting a training run; leave at least ~1 GB free.

### Error: `UnicodeEncodeError` when printing Chinese strings

**Cause:** the terminal encoding is not UTF-8 (Windows default).

**Solution:**

```bash
# In the Anaconda Prompt
chcp 65001
set PYTHONIOENCODING=utf-8
```

Then relaunch the notebook server.

**Prevention:** on Windows, prefer running Jupyter from the **Anaconda Prompt** with UTF-8 enabled, or use WSL.

### Error: `ValueError: zero-size array to reduction operation fmin which has no identity` on Apple Silicon

**Cause:** MXNet 1.7 does not run natively on Apple Silicon; PyTorch older than 1.12 requires Rosetta.

**Solution:** switch to the PyTorch or TensorFlow tab, and use a recent build (`torch>=2.0`). The book's pinned versions were released before the M-series Macs; later versions work with the book's code.

**Prevention:** on Apple Silicon, skip MXNet. PyTorch MPS backend is the smoothest path.

### Error: notebook downloads stall on `d2l-data.s3-accelerate.amazonaws.com`

**Cause:** firewall or slow international bandwidth.

**Solution:** manually download the dataset ZIP (URLs are inside `d2l/<framework>.py`'s `DATA_HUB` dict) and place it in `~/.d2l/` before running the cell that needs it. Inside mainland China, mirror services and Kaggle-hosted copies of Fashion-MNIST, CIFAR-10, and the time-machine text sometimes load faster.

**Prevention:** pre-warm the cache before a long study session.

### Error: `matplotlib` figures render as static PNGs, not SVGs

**Cause:** the matplotlib inline backend was not reset to SVG.

**Solution:** call `d2l.use_svg_display()` at the top of the notebook, or re-import with `from d2l import torch as d2l` which runs `use_svg_display()` on import via the first `d2l.plot()` call.

**Prevention:** always `from d2l import <framework> as d2l` *before* creating figures.

### Error: `IndexError: index ... out of bounds` when iterating `data_iter`

**Cause:** the dataset was partially downloaded and is corrupt.

**Solution:** delete the `~/.d2l/` cache and rerun the notebook; the helper library re-downloads and re-verifies.

**Prevention:** do not kill the download cell midway on the first run.

### Error: `RuntimeError: one of the variables needed for gradient computation has been modified by an inplace operation`

**Cause:** a framework-specific in-place op conflicts with autograd. Most often this appears when readers adapt a from-scratch chapter and accidentally use `+=` on a parameter.

**Solution:** replace `w += grad` with `w = w - lr * grad` (out-of-place) or wrap the update in `with torch.no_grad():` / `param[:] = ...`.

**Prevention:** study `chapter_linear-networks/linear-regression-scratch.md` carefully — its `sgd()` is the template for correct in-place parameter updates.

> [!CAUTION]
> In-place parameter updates (`+=`, `-=`) during gradient computation will silently corrupt the autograd graph in PyTorch. The resulting errors may not appear until several training iterations later, making them difficult to debug. Always use `with torch.no_grad():` for manual parameter updates.

### Error: figures show boxes instead of Chinese characters

**Cause:** the system font cache does not include a CJK font.

**Solution:** on Linux, install Noto CJK: `sudo apt install fonts-noto-cjk`. On macOS, PingFang is installed by default. On Windows, install Source Han Sans SC from [adobe-fonts/source-han-sans](https://github.com/adobe-fonts/source-han-sans/releases).

**Prevention:** this only affects rebuilding the book's PDF yourself; the pre-rendered PDFs at `zh-v2.d2l.ai` already contain the correct fonts.

### Error: `d2l.train_ch3: TypeError: ... got an unexpected keyword argument`

**Cause:** you are using a `d2l` package version that does not match the chapter you are reading. Chapters 3-5 and chapters 13+ evolved their helper signatures.

**Solution:** reinstall the pinned version: `pip install --force-reinstall d2l==0.17.6`. Make sure the book content you are reading is the 2.0.0 release.

**Prevention:** pin the version; do not `pip install -U d2l`.

### Error: `ImportError: cannot import name 'npx' from 'mxnet'`

**Cause:** the MXNet version is newer than `1.7.0`; the `npx` namespace layout changed.

**Solution:** `pip install mxnet==1.7.0.post1` (CPU) or `pip install mxnet-cu101==1.7.0` (CUDA 10.1).

**Prevention:** use the exact versions in `chapter_installation/index.md`.

### Error: Jupyter kernel dies on first `import torch`

**Cause:** an incompatible CUDA/driver combination, or low memory.

**Solution:** rerun outside Jupyter: `python -c "import torch; print(torch.__version__)"`. The Python error message will pinpoint the issue. Common fixes: upgrade the driver, install the CPU wheel, or add swap.

**Prevention:** verify the framework imports cleanly from a plain `python` shell before using it in Jupyter.

### Error: exercises reference a figure that does not exist in the notebook

**Cause:** the exercise references a later section; the figure lives in a subsequent notebook.

**Solution:** read the online HTML for navigation — the website links figure references across chapters. The standalone `.ipynb` files do not have cross-notebook hyperlinks.

**Prevention:** keep [zh.d2l.ai](https://zh.d2l.ai) open in a browser tab alongside the local notebooks.

---

## 7. FAQ

**Q: Which edition of the book does this repository correspond to?**

Version `2.0.0`, the second edition of the Chinese book, matching [zh.d2l.ai](https://zh.d2l.ai). The first edition lives at [zh-v1.d2l.ai](https://zh-v1.d2l.ai) and in the repository's historical tags.

**Q: Is the English version in the same repository?**

No. `d2l-ai/d2l-en` is the upstream English source; `d2l-ai/d2l-zh` is the Chinese translation. Paragraph-level English originals are retained as `_origin.md` files inside each chapter folder for translators to keep in sync.

**Q: Do I need a GPU to read the book?**

Not for the first six chapters (`chapter_preface/` through `chapter_multilayer-perceptrons/`). From `chapter_convolutional-modern/` onward, a GPU is strongly recommended.

**Q: Can I run everything on a Mac?**

Yes, using the PyTorch tab. On Apple Silicon, PyTorch's MPS backend accelerates many (not all) ops. MXNet does not support Apple Silicon well — choose a different framework.

**Q: Which framework gets the most maintenance?**

PyTorch and PaddlePaddle are the most actively updated in this repository. TensorFlow is maintained. MXNet's upstream maintenance has wound down; the book's MXNet path still works against the pinned versions but is not a great choice for a fresh reader.

**Q: How do I cite the book in a paper?**

The `README.md` provides a BibTeX entry:

```bibtex
@book{zhang2023dive,
    title={Dive into Deep Learning},
    author={Zhang, Aston and Lipton, Zachary C. and Li, Mu and Smola, Alexander J.},
    publisher={Cambridge University Press},
    note={\url{https://D2L.ai}},
    year={2023}
}
```

**Q: Is there a paid version?**

There is a print edition published by Cambridge University Press (人民邮电出版社 in mainland China). The online edition, PDFs, and notebooks are free.

**Q: Can I use the code in my own projects?**

Yes. The code is MIT-0 licensed (`setup.py`, `config.ini`); the book content is CC-BY-SA-4.0. Attribute the authors and inherit share-alike for derivative written work.

**Q: My notebook shows different loss numbers than the book — is that a bug?**

Most likely not. The book's numbers are from a specific random seed, framework version, and hardware. Expect variance in the third decimal place between runs. If your numbers are orders of magnitude off, re-check batch size, learning rate, and framework version.

**Q: Where are the answers to the exercises?**

There is no official answer key — the exercises are pedagogical. Post your solutions on the discussion forum link at the end of each section (`discuss.d2l.ai`).

**Q: Can I skip the "from scratch" versions and read only the "concise" ones?**

You can, and your reading time will drop by roughly half. But you will understand the abstractions far better if you read both pairs.

**Q: How do I report a typo?**

Edit the Markdown file directly on GitHub (click the pencil icon on any file) and open a pull request. See the **Admin Guide** for the full contributor workflow.

**Q: What if I want to translate the book into another language?**

Fork `d2l-ai/d2l-en` and follow its translation conventions. The Chinese edition is one such fork. The `_origin.md` dual-file layout used here is the recommended pattern for keeping a translation in sync with upstream.

**Q: Does the book cover generative models / diffusion / LLMs?**

The 2.0.0 release covers up to Transformers and BERT pre-training. Diffusion models and larger-scale generative architectures are tracked in the English upstream `d2l-ai/d2l-en` for later editions; they are not yet in the Chinese release.

**Q: Can I run notebooks in VS Code instead of Jupyter?**

Yes. Install the Jupyter extension for VS Code, select the `d2l` conda environment as the kernel, and open any `.ipynb` file. All plots render inline, same as the browser UI.

**Q: Why does `config.ini` list `libs = ... -U mxnet-cu101==1.7.0`?**

That is the Colab install command used when the book's Colab mirrors build their notebooks. The `-U` forces an upgrade over Colab's pre-installed MXNet. You do **not** need to run that command locally.

---

## 8. Additional Resources

- **Official site (Chinese v2):** [zh.d2l.ai](https://zh.d2l.ai)
- **First edition (legacy Chinese):** [zh-v1.d2l.ai](https://zh-v1.d2l.ai)
- **English upstream:** [github.com/d2l-ai/d2l-en](https://github.com/d2l-ai/d2l-en)
- **Discussion forum:** [discuss.d2l.ai/c/chinese-version/16](https://discuss.d2l.ai/c/chinese-version/16)
- **Berkeley STAT 157 course materials:** [courses.d2l.ai/berkeley-stat-157](http://courses.d2l.ai/berkeley-stat-157/index.html)
- **Chinese course site:** [courses.d2l.ai/zh-v2](https://courses.d2l.ai/zh-v2/)
- **Colab per framework:**
  - MXNet — [github.com/d2l-ai/d2l-zh-colab](https://github.com/d2l-ai/d2l-zh-colab)
  - PyTorch — [github.com/d2l-ai/d2l-zh-pytorch-colab](https://github.com/d2l-ai/d2l-zh-pytorch-colab)
  - TensorFlow — [github.com/d2l-ai/d2l-zh-tensorflow-colab](https://github.com/d2l-ai/d2l-zh-tensorflow-colab)
  - PaddlePaddle — [github.com/d2l-ai/d2l-zh-paddle-colab](https://github.com/d2l-ai/d2l-zh-paddle-colab)
- **SageMaker per framework:** `d2l-ai/d2l-zh-sagemaker`, `d2l-zh-pytorch-sagemaker`, `d2l-zh-tensorflow-sagemaker`, `d2l-zh-paddle-sagemaker`
- **Slides (PyTorch):** [github.com/d2l-ai/d2l-zh-pytorch-slides](https://github.com/d2l-ai/d2l-zh-pytorch-slides)
- **Release archives on S3:**
  - `s3://d2l-webdata/releases/d2l-zh/d2l-zh-1.0.zip`
  - `s3://d2l-webdata/releases/d2l-zh/d2l-zh-1.1.zip`
  - `s3://d2l-webdata/releases/d2l-zh/d2l-zh-2.0.0.zip`

---

_Generated May 2026 from d2l-ai/d2l-zh at e6b18cc. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._