ageron/handson-ml3: nineteen notebooks that ship with a deep learning book

The file tree is the book's table of contents

Open the repository and the shape of the book is the shape of the directory. There are nineteen numbered notebooks, `01_the_machine_learning_landscape.ipynb` through `19_training_and_deploying_at_scale.ipynb`, and they run in that order. An end to end housing price project comes first, then classification, linear models, support vector machines, decision trees, ensemble learning, dimensionality reduction and unsupervised learning. The Keras and TensorFlow material starts at chapter 10 and runs through custom models, data loading and preprocessing, convolutional networks, sequences, attention, autoencoders with GANs and diffusion models, and reinforcement learning.

Alongside the numbered files sit a handful of entries that are not chapters. `math_differential_calculus.ipynb`, `math_linear_algebra.ipynb` and `tools_numpy.ipynb`, `tools_pandas.ipynb`, `tools_matplotlib.ipynb` are background material. Three `extra_` notebooks sit outside the main sequence: `extra_ann_architectures.ipynb`, `extra_autodiff.ipynb` and `extra_gradient_descent_comparison.ipynb`. Four markdown documents matter more than they look: `CHANGES.md`, `INSTALL.md`, `ml-project-checklist.md` and `LICENSE`, plus `book_equations.pdf` for the derivations.

The project is not archived and the last push landed on 2026-05-19, so this is a repository that still moves. With 14184 stars and 5321 forks it is also one of the most widely read machine learning repositories on GitHub, which is why the contributor list in the README reads like a changelog of real bug reports.

Building the environment with conda and a user kernel

The README's local install path is deliberately short and deliberately explicit about not typing the dollar signs. You need Anaconda or Miniconda, git, and if you have a TensorFlow compatible GPU, the driver plus a matching CUDA and cuDNN.

$ git clone https://github.com/ageron/handson-ml3.git
$ cd handson-ml3
$ conda env create -f environment.yml
$ conda activate homl3
$ python -m ipykernel install --user --name=python3
$ jupyter notebook

That middle line, `python -m ipykernel install --user --name=python3`, is the step people skip and then wonder why their kernel is missing. The last line launches the classic notebook server rather than JupyterLab, even though the requirements pin JupyterLab, which is a small inconsistency worth knowing about.

`requirements.txt` is the flat counterpart to `environment.yml`, and it is the more interesting file to read because the comments explain the optional pieces. Every library is pinned with a compatible release operator rather than an exact version:

scikit-learn~=1.3.2
xgboost~=2.0.2
transformers~=4.35.0
tensorflow~=2.14.0
tensorflow-serving-api~=2.14.0
keras-tuner~=1.4.6
gymnasium[Box2D,atari,accept-rom-license]~=0.29.1
google-cloud-aiplatform~=1.36.2

The comments map those to chapters: XGBoost is only used in chapter 7, transformers only in chapter 16, the TensorFlow serving API only in chapter 18, and the Google Cloud AI Platform package only in chapter 19. NumPy is held at 1.26.2 and pandas at 2.1.3, which is the kind of pin that keeps old notebooks from breaking when a library changes behaviour underneath them.

Colab first, Docker second, nbviewer for looking only

The README puts Colab first and marks it recommended, which is the right default for a teaching repository. The badge opens the whole project in a temporary Google environment with nothing to install. The warning attached to it is the part that matters: anything you write is deleted after a while, so download any data you care about before the session ends.

Other hosted runners are listed but hedged. The author says other services may work as well but that he has not fully tested them, and then names Kaggle, Binder and Deepnote. That hedging is honest and worth taking at face value. Colab works because the dependency versions are modern enough for a current hosted image; the others depend on images nobody in this repository controls.

For reading without executing, there is an nbviewer link and a note that GitHub's own notebook viewer also works but is slower, renders the math equations unreliably, and often fails to open the larger notebooks. Chapter 16 and chapter 17 are large files, so that failure is not hypothetical.

The Docker route lives in its own `docker/` directory, credited in the README to two community contributors. The image is the answer when you want reproducible training runs or a GPU without fighting host CUDA versions, which is exactly what chapters 11 and 14 need.

The extras cover autodiff and gradient descent from first principles

Three notebooks sit outside the numbered sequence and they answer the questions the chapters assume you already have. `extra_autodiff.ipynb` builds automatic differentiation by hand, `extra_gradient_descent_comparison.ipynb` compares optimizers, and `extra_ann_architectures.ipynb` looks at specific network architectures. None of them are book chapters, which means they are free to be slower and more explicit than teaching material usually gets to be.

The math and tools notebooks play a similar role at the front of the curriculum. `math_linear_algebra.ipynb` and `math_differential_calculus.ipynb` are the two dependencies that readers most often skip and later regret skipping, because chapter 11 asks you to reason about gradients and chapter 14 asks you to reason about convolution. The three `tools_` notebooks give NumPy, pandas and Matplotlib a shared introduction so that the pandas work in chapter 2 and the plotting throughout are not the first time you meet them.

`ml-project-checklist.md` is a quiet standout. A one page checklist for structuring a machine learning project is the kind of artifact that gets reused long after the book is finished, and it is the file to read if you want the method without any of the code.

Chapter 19 is the only part that leaves your laptop

Nineteen chapters in, the repository changes gear. The requirements file carries `tensorflow-serving-api~=2.14.0` with a comment saying it is needed for chapter 18, and `google-cloud-aiplatform~=1.36.2` marked as used only in chapter 19. `tensorflow-datasets` and `tensorflow-hub` arrive for the same stretch, and `keras-tuner` is labelled as used in chapters 10 and 19 for hyperparameter tuning.

Chapter 19 covers training and deploying at scale, which in practice means model export, serving, and a hosted training path. The presence of `apt.txt` in the tree suggests the setup for a remote Linux machine or cloud instance, and the README's thanks to the Google ML Developer Programs team for providing Google Cloud credit says plainly where that path leads. Chapters 1 through 18 need nothing but your machine. Chapter 19 needs an account and a bill.

Reinforcement learning in chapter 18 is the other heavy dependency, with Gymnasium installed with the Box2D, Atari and ROM license extras and Swig required to build it. The comments warn that the Windows route needs Swig and Microsoft C++ Build Tools and that Anaconda is much easier. Chapter 18 also pulls in the serving API, so the reinforcement learning chapter and the deployment chapter are adjacent in dependency terms even though they are far apart in subject.

The README answers setup questions and stops there

Everything about how to run the notebooks is in the README, including a FAQ section that handles the failures people actually hit. It recommends Python 3.10, which is the version the installation instructions give you, and notes that anything from 3.7 upward should work. It explains that a `load_housing_data()` HTTP error usually means the code in the notebook was not run exactly as written, and that an SSL error on macOS is a certificate problem fixed by running the Install Certificates command from an official Python install or `sudo port install curl-ca-bundle` for MacPorts users.

Beyond that, the README delegates. Updates to the project and updates to the Python libraries both point at `INSTALL.md` rather than answering here. The exercises are in the book, the derivations are in `book_equations.pdf`, and the prose explanation of each technique lives in the O'Reilly text at homl.info.

So the honest division of labour is this. The repository is where the code lives and where people fix code, which the contributor list shows happening: named reviewers walked every notebook, and a long tail of pull requests fixed errors that would otherwise still be in the text. The book is where the teaching lives. Anyone expecting a standalone curriculum here will find the notebooks assume you have the book open next to them.

Editorial conclusion

What this repository is good at is being the companion code for one specific book, kept honest by hundreds of pull requests from readers who ran every notebook and reported what broke. It is not a general purpose machine learning starter kit: the chapter order follows the book's table of contents, the library versions are deliberately frozen at the 2.14 era of TensorFlow, and chapter 19 assumes you are willing to open a cloud account. Start with index.ipynb, which links the notebooks in order, or with the Colab badge if you would rather not build the conda environment, and treat INSTALL.md as the file that answers version questions the README only gestures at.

Frequently asked questions

Official sources

1. ageron/handson-ml3 on GitHub
2. Issues
3. License: Apache-2.0
4. README