ageron/handson-ml2: The Second-Edition Notebooks, and Why the README Points Elsewhere

What handson-ml2 actually contains, and who it is for

This repository is the companion code for the second edition of Hands-On Machine Learning with Scikit-Learn, Keras and TensorFlow, published in 2019. It holds nineteen numbered notebooks plus a few extras, and the README describes the set as the example code and solutions to the exercises in that book. The repository layout backs this up: 01_the_machine_learning_landscape.ipynb through 19_training_and_deploying_at_scale.ipynb, with side files for NumPy, pandas, Matplotlib, linear algebra and differential calculus.

The audience is narrow and specific. You are reading the second edition, you want to run the code rather than only read it, and you want the notebook to match the page. A separate ml-project-checklist.md sits at the top level for people who want a checklist rather than a tutorial. If you are starting from scratch with no book in hand, the README is blunt: the third edition is available, and a PyTorch version exists as well.

The first line of the README carries a warning that this edition is now outdated. That warning is the most important fact about the project, and it shapes every decision below.

How the notebooks, environment file and datasets fit together

There is no library here and no importable package. The unit of work is the notebook. Each numbered file is self-contained enough to open and run, and the chapters that need data call helper functions defined inside the notebook itself. Chapter 2 is the clearest example: the README's FAQ says you must call fetch_housing_data() before load_housing_data(), which tells you the download step is a separate function call and not an import side effect.

Dependencies are declared twice, and the two files disagree in spirit. environment.yml is the conda path and the one the README recommends. requirements.txt is the pip fallback, and it opens with a warning that Anaconda is highly recommended instead, especially on Windows or with a GPU. The pip file pins tensorflow~=2.6.0, numpy~=1.19.5, scikit-learn~=1.0 and pandas~=1.3.3, and marks several packages as optional per chapter: xgboost for chapter 7, transformers for chapter 16, tensorflow-serving-api for chapter 19, tfx for chapter 13, tensorflow-addons for chapter 16, and gym with Box2D and atari extras for chapter 18.

That optionality is a real design choice. Installing everything gives you a heavy environment for chapters you may never open. The reinforcement learning block is the heaviest: requirements.txt notes that gym[Box2D] on Windows needs Swig and the Microsoft C++ Build Tools, and says Anaconda is much easier. The datasets directory and the images directory are checked in, so some material is available offline, but the notebooks that fetch remote data still need network access at run time.

Installing handson-ml2 with conda and running your first notebook

The README's local installation path assumes Anaconda or Miniconda, git, and, if you have a TensorFlow-compatible GPU, the NVIDIA driver plus matching CUDA and cuDNN. Clone the repository and enter it first.

git clone https://github.com/ageron/handson-ml2.git
cd handson-ml2

Then create the environment from the checked-in file and activate it. The environment name in the README is tf2, which is the name you pass to conda activate.

conda env create -f environment.yml
conda activate tf2
python -m ipykernel install --user --name=python3
jupyter notebook

The ipykernel line registers the environment as a Jupyter kernel named python3, so notebooks launched from this directory pick it up. After jupyter notebook starts, open index.ipynb for the table of contents, or go straight to 02_end_to_end_machine_learning_project.ipynb. In that notebook, run the cell that defines fetch_housing_data() before the cell that calls load_housing_data(); the FAQ is explicit that reversing the order is the usual cause of the error people report. If the fetch fails with an HTTP error, the README suggests running the exact notebook code rather than a modified version, and checking your network configuration.

On macOS, an SSL certificate error during the download is covered in the FAQ, which points to a StackOverflow question and, for Python installed from the official installer, to running the Install Certificates.command script under /Applications/Python 3.8/ with the version number adjusted to whatever you installed. The README recommends Python 3.8 and notes that some libraries do not yet support 3.9 or 3.10. If you would rather not touch conda at all, the README points to the docker directory for container instructions.

The pinned TensorFlow 2.6 environment is the real constraint

The most practical limitation is not conceptual, it is the version pin. requirements.txt asks for tensorflow~=2.6.0 and tensorboard~=2.7.0, with numpy~=1.19.5 underneath. Those are 2021 releases. A fresh environment built from this file on a current machine may fail to resolve, and the README does not document a fallback beyond using Anaconda instead of pip. Nothing in the repository promises that the pins have been refreshed, and no releases are listed for the project.

The second limitation is scope drift between the book and the ecosystem. The README itself says the edition came out in 2019 and is outdated. Notebooks written against TensorFlow 2.6 will not match current TensorFlow APIs in every cell, and the README does not enumerate which cells break. If your goal is to learn current Keras or current scikit-learn idioms, this is the wrong repository; the README says so in its first line.

The third is the online services. Colab, Kaggle, Binder and Deepnote are offered as ways to run the notebooks without installing anything, and the README warns in capitals that these are temporary environments where anything you do is deleted after a while. Download any data you care about. That warning is easy to skim past and expensive to ignore.

Finally, the maintenance picture. The repository is not archived, and the last push was on 2026-05-19. That is recent enough that the project is not abandoned, but the README's own framing, plus the absence of releases, means you should treat this as a frozen teaching artifact rather than a codebase tracking upstream libraries.

handson-ml3 and handson-mlp: what changes in the successor

The obvious alternative is the one the README names: ageron/handson-ml3, the third edition of the same book. The difference is not a rewrite of the same material in a new style; it is a different edition with its own text, and the notebooks track that text. If you are holding the third edition, handson-ml3 is the matching code and handson-ml2 is the previous one. Choosing between them is mostly a question of which book is on your desk.

The second alternative is ageron/handson-mlp, which the README describes as a PyTorch version. That is a framework swap, not an edition swap. The second edition's notebooks are built on Keras and TensorFlow, so the chapter on training deep neural networks, the chapters on CNNs and RNNs, and the chapter on custom models and training all assume TensorFlow APIs. A PyTorch reader would be translating every cell rather than running it.

The README also links to many translations of the book. That matters if your reason for being here is language rather than framework: the translations follow the book, and the book edition determines which notebook repository matches.

One thing none of these alternatives fixes for you: the first edition lives at ageron/handson-ml, and the README points there explicitly for readers who have that older book. Three repositories, three editions, and the correct one is decided entirely by which printing you are reading.

Licence, updating an existing clone, and the cost of staying on this edition

The repository is Apache-2.0. For a notebook collection that means you can reuse and adapt the code with the usual attribution and notice requirements, but the book text itself is a separate O'Reilly product and is not covered by that licence. The README does not discuss the book's terms, and nothing here should be read as legal advice; check the licence file in the repository and the book's own terms if you plan to redistribute anything beyond the code.

Updating an existing local clone is handled by INSTALL.md rather than the README. The README's FAQ asks two questions about updates, one for the project itself and one for the Python libraries under Anaconda, and answers both by pointing at INSTALL.md. That file is where you should look before running any pull or conda update command, because the environment pins and the notebook code move together.

The upgrade cost is the honest reason to think twice. Moving from this repository to handson-ml3 is not a dependency bump; it is a switch to a different edition's notebooks, with different chapter numbering and different library versions. If you have notes, partial solutions or modified notebooks built on handson-ml2, that work does not transfer cleanly. The cheap moment to choose the right edition is before you start, not after chapter 12.

Editorial conclusion

Adopt handson-ml2 when you are working through the 2019 second edition and need the notebook code to match the printed text, or when you want a pinned TensorFlow 2.6 environment that still resolves. Do not adopt it for new work: the README opens by calling this edition outdated and points to ageron/handson-ml3, with a PyTorch version at ageron/handson-mlp. Before committing, check that environment.yml still solves on your platform, and read the docker directory if you want to skip conda entirely.

Frequently asked questions

Official sources

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