handson-ml2: the second-edition notebooks, and what the deprecation notice actually costs you

What the repository is actually for

This is not a library. There is no package to install and no API to import. The repository holds the example code and the exercise solutions for the second edition of Hands-On Machine Learning with Scikit-Learn, Keras and TensorFlow, published in 2019. The README describes it as teaching the fundamentals of machine learning in Python, and the primary language listed for the repository is Jupyter Notebook.

The audience is therefore narrow and specific: someone reading that edition, who wants to run the cells rather than read them, and who wants to compare their answers to the exercises against a reference implementation. If you are not holding the book, you are looking at a set of notebooks whose ordering and commentary assume you are. That is a real constraint, not a formality. The notebooks are the code half of a two-part artefact.

The deprecation notice is the first thing you read

The README begins with a warning that the edition is outdated, followed by links to the third edition at ageron/handson-ml3, a PyTorch version at ageron/handson-mlp, and a translations page at homl.info. The body text repeats the point: the project is for the second edition, which came out in 2019.

So the maintainer has done the honest thing and put the status above the fold. The repository is not archived, and its last push date is recent, but the README does not promise ongoing development of the second-edition material. Treat the deprecation as the project's own framing of its maintenance state rather than as a rumour you have to infer.

The practical consequence is a fork in the road. If your goal is to learn machine learning in Python today, the README itself routes you to handson-ml3 or handson-mlp. If your goal is to follow the 2019 text, handson-ml2 is the correct match and the newer repositories will drift from your page numbers and from the APIs your book describes.

Getting it running: conda, the tf2 environment, and Jupyter

The installation path in the README assumes Anaconda or Miniconda, git, and, for a TensorFlow-compatible GPU, the NVIDIA driver plus the matching CUDA and cuDNN versions. Clone and enter the repository:

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

Then create the environment, activate it, and register the kernel:

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

Finally start the notebook server:

$ jupyter notebook

The environment name is tf2, and it comes from environment.yml at the repository root. The ipykernel step matters because without it the Jupyter kernel list may not point at the environment you just built. INSTALL.md holds the longer instructions, including how to update a local install and how to update Python libraries under Anaconda.

There is also a docker directory, contributed by Steven Bunkley and Ziembla according to the README, with its own instructions. If you would rather not manage conda at all, the README lists hosted options: Colab, Kaggle, Binder, and Deepnote, with a link to nbviewer for reading notebooks without executing them. The README recommends Colab or Kaggle for the free GPUs and TPUs, and warns that these services provide temporary environments where your work is deleted after a while.

Python 3.8 and the data-loading order

The FAQ answers two questions that will otherwise cost you an afternoon. The first is the Python version: the author recommends 3.8, which is what the documented installation produces, and notes that most code works on other Python 3 versions but that some libraries did not support 3.9 or 3.10 at the time of writing. That is a pinned-version project in practice, and pinning is the point. The notebooks were written against a 2019 stack, and environment.yml is how the author keeps that stack reproducible.

The second is the housing data error. If load_housing_data() fails, the FAQ says to call fetch_housing_data() first. If you get an HTTP error, run the exact code from the notebook, copying and pasting if necessary, and then check your network configuration. That ordering is not a bug, it is the notebook teaching a two-step download-then-load flow, and it is easy to skip a cell when you are jumping around.

The FAQ also covers an SSL error on macOS. The suggested fixes are to run the certificate installer shipped with the official Python package, for example /Applications/Python\ 3.8/Install\ Certificates.command with the version adjusted to whatever you installed, or, for a MacPorts Python, sudo port install curl-ca-bundle.

What you give up by staying on the second edition

The clearest limitation is stated by the project itself: the edition is outdated. The README does not enumerate which APIs have moved on, and this material does not let me list them, so I will not guess. What can be said is that a 2019 book on Scikit-Learn, Keras and TensorFlow describes interfaces that have since been revised, and the notebooks inherit whatever those revisions broke.

That makes handson-ml2 the wrong tool for two jobs. It is wrong for learning current practice, because the current practice is what handson-ml3 and handson-mlp cover. It is also wrong as a pinned base for production work: environment.yml is tuned for the notebooks, not for an application you intend to maintain, and the FAQ's Python 3.8 recommendation reflects the 2019 dependency set rather than a forward-looking support policy.

There is a third case worth naming. If you want to read the notebooks without running anything, the README notes that GitHub's own viewer works but is not ideal: it is slower, mathematical equations are not always displayed correctly, and large notebooks often fail to open. Use nbviewer for that. This is a small point but a concrete one, and it is the kind of detail that determines whether a reading session goes smoothly.

handson-ml3 and handson-mlp: the same author, a different target

The alternative the README names first is handson-ml3, the third edition of the same book. The difference in approach is not a matter of quality, it is a matter of which text you are reading. handson-ml3 tracks a newer edition, so its notebooks, its library versions and its explanations correspond to a later state of Scikit-Learn, Keras and TensorFlow. If your question is how to do something now, that repository is the one the author points you to, and handson-ml2 is the one he tells you is outdated.

The second alternative is handson-mlp, a PyTorch version of the material. That is a framework substitution rather than an edition bump: the teaching sequence stays in the same family, but the deep learning chapters are expressed in PyTorch instead of TensorFlow and Keras. If your stack is PyTorch, handson-ml2 is a poor fit for the later chapters regardless of which edition you own, because the code you would be typing does not match the framework you use.

A third fork exists for completeness: ageron/handson-ml holds the first-edition notebooks, which the README mentions for readers who are looking for that older material.

Licence and the cost of keeping a fork alive

The repository is licensed Apache-2.0. That is a permissive licence, and it is the same family used across the author's notebook repositories, but I am not going to tell you what it permits in your situation. Read the LICENSE file in the repository and, if the answer matters commercially, get proper advice.

On maintenance cost, the material supports a limited but useful statement. The README links to INSTALL.md for two upgrade paths: updating a local installation of the project, and updating Python libraries under Anaconda. So the project documents how to refresh an environment rather than freezing it forever. That said, the deprecation banner means you should not expect the second-edition notebooks to be revised when upstream libraries change. If you fork handson-ml2 to teach from, the ongoing work of keeping environment.yml installable is yours, and the author has already directed new readers elsewhere.

That is the honest trade. You get a complete, self-consistent set of notebooks tied to a specific 2019 text, plus a documented conda environment and a Docker path. You take on the version drift yourself, and you accept that the repository's own front page recommends a different one.

Editorial conclusion

Adopt handson-ml2 only if you are working through the 2019 second edition and need the notebooks to match the printed text, or if you want to read the exercise solutions as a reference. Do not adopt it for new code: the README states the edition is outdated and names handson-ml3 and handson-mlp as the current paths. Before cloning, check which Python version your environment resolves to, because the FAQ recommends Python 3.8 and notes that some libraries did not support 3.9 or 3.10 at the time of writing.

Official sources

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