ageron/handson-ml: the first-edition notebooks, and why the README sends you elsewhere

What the first-edition notebooks actually contain

The repository is the companion code for the 2017 O'Reilly book Hands-On Machine Learning with Scikit-Learn and TensorFlow. It holds the example code and the exercise solutions for that edition, written as Jupyter notebooks. The subject matter spans the fundamentals of machine learning in Python, with scikit-learn and TensorFlow as the two named libraries, and the topics list adds deep learning, neural networks and distributed training.

The audience is narrow and clearly defined. This is teaching material for someone following the first edition page by page. The README states that the project is for the first edition and that it is now outdated, and the repository description carries a DEPRECATED marker pointing at two successors. That is not a soft warning buried in a changelog. It is the first line of the README and the description field, which means anyone arriving from a search result sees the redirect before they see the notebooks.

If you are not reading the 2017 edition, the notebooks here are not a general machine learning tutorial. They are a frozen snapshot of how the material was taught at that time, and the code reflects the library versions of that period.

The TensorFlow 1 conda environment is the real constraint

The installation path in the README is explicit. You install Anaconda or Miniconda and git, and if you have a TensorFlow-compatible GPU you also install the GPU driver plus the matching CUDA and cuDNN versions. Then you clone the repository, create the environment from the checked-in environment.yml, activate it, and register the kernel.

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

The environment is named tf1, which is the clearest signal of what you are getting. The FAQ recommends Python 3.7 and says that is the version the instructions produce, adding that most code works on other Python 3 versions but some libraries do not support 3.8 or 3.9. So the supported configuration is a specific interpreter plus a specific dependency set from environment.yml, and the further you move from it the more you are on your own. Anyone who has tried to install an old TensorFlow 1 release on a current Python will recognise the shape of this problem.

The README also documents two failure modes that recur. Calling load_housing_data() before fetch_housing_data() produces an error, and an HTTP error usually means the code was not copied exactly as written. On macOS, an SSL error is handled by running the certificate installer that ships with the official Python package, or by installing curl-ca-bundle through MacPorts. These are small notes, but they are the kind of thing that stops a beginner cold, which is exactly the reader this repository was written for.

Four ways to open the notebooks without installing anything

The README leads with hosted options before it gets to local installation, and the ordering is deliberate. Colaboratory is marked as recommended, with a link that opens the repository directly. Binder and Deepnote are offered as alternatives, and nbviewer is listed for reading without executing. The README notes that GitHub's own notebook viewer works but is slower and does not always render the math equations correctly, which is a concrete reason to prefer nbviewer for reading.

The warning attached to these services matters more than the links. The README states plainly that they provide temporary environments and that anything you do will be deleted after a while, so you should download any data you care about. There is a second note about Binder: it usually starts quickly, but when handson-ml is updated it builds a new environment from scratch and that can take a long time.

There is also a docker directory with instructions, credited in the contributors section to Steven Bunkley and Ziembla. That is the third route: a container instead of a conda environment. The README does not describe what the image contains, so if you need to know which library versions end up installed, read the docker directory itself rather than assuming it mirrors environment.yml.

The update path the README refuses to hide

Most deprecated repositories leave the deprecation to a badge or an archive notice. This one puts the replacement in the largest text on the page: the third edition of the book is available, as is a PyTorch version, and there are many translations. The repository description repeats the redirect. The material underneath is preserved rather than deleted, so the notebooks remain readable and the exercise solutions remain available to anyone still on the first edition.

That combination is honest but slightly awkward. A reader who lands on a notebook from a search engine may not scroll to the top of the README, and the code they find will not match the library versions they have installed. The FAQ answer recommending Python 3.7 is the tell: it was written when 3.7 was current, and the note that some libraries do not yet support 3.8 or 3.9 has aged in the opposite direction from the ecosystem around it.

What the repository does not offer is a migration guide. There is no table mapping first-edition notebooks to their third-edition equivalents, and no list of which exercises changed. If you are halfway through the first edition, the README tells you a newer edition exists but not how the two line up. That gap is the main practical cost of using this repository today.

handson-ml3 and the PyTorch version: what actually differs

The README names two successors. handson-ml3 is the third edition of the same book, and handson-mlp is a PyTorch version. The difference that matters is not cosmetic. This repository is built around TensorFlow 1, which is why the conda environment is called tf1 and why the FAQ has to pin a Python version. TensorFlow 1 and the TensorFlow 2 line that followed it differ in execution model and API surface, so code written against the older one does not transfer by renaming an import. The third edition exists precisely because the book's framework content had to be rewritten.

The PyTorch version is a different axis of change. It is not a newer edition of the same text but the same teaching material expressed in a different framework, which matters if your team has standardised on PyTorch and you want the book's exercises in that idiom rather than in TensorFlow.

So the choice is between three repositories, not between a current one and an obsolete one. If you need TensorFlow 1 examples specifically, perhaps to read code you have inherited, this is the only one of the three that will match. If you are learning the material for the first time, the third edition is the one the author points to. If your reason for being here is framework preference rather than edition, handson-mlp is the relevant link.

Apache-2.0, and what it does not cover

The repository is licensed under Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved. For a set of teaching notebooks that is a permissive arrangement, and the exercise solutions can be reused in internal training material without the friction of a copyleft licence.

The licence covers the code in the repository. It does not cover the book. The README links to the O'Reilly learning platform and displays the cover image, and the notebooks are described as example code and solutions for that book. Copying the prose of the book into your own material is a separate question from copying the notebooks, and the repository does not address it. That is a distinction worth keeping in mind if you plan to build a course around this material, and it is a question for whoever handles licensing at your organisation rather than something this review can settle.

Who should clone this, and who should not

Clone it if you are working through the 2017 first edition and want the notebooks to match the text, or if you have inherited TensorFlow 1 code and want a worked example of how it was written. The conda environment gives you a reproducible target, and the hosted options let you read the notebooks before committing to a local install.

Do not clone it if you are starting from scratch. The README's own first line sends you to the third edition, and the Python 3.7 recommendation is a sign of how far the dependency set has drifted from current tooling. Do not treat the notebooks as a reference for current TensorFlow practice either, since the environment name tf1 makes the version explicit and the API has moved on.

Before you spend time on setup, open the top of the README and confirm which edition you are actually following, then check whether the notebook you want already exists in handson-ml3 or handson-mlp. If you do proceed locally, run conda env create -f environment.yml and conda activate tf1 exactly as written, and keep to the Python version the FAQ names rather than substituting a newer interpreter. The repository still works as a record of how the material was taught in 2017. It is not a starting point for learning machine learning in 2026.

Editorial conclusion

Use this repository only if you are working through the 2017 first edition of the book, or if you specifically need TensorFlow 1.x example code and can run it in the pinned conda environment. Everyone starting fresh should go to handson-ml3 or the PyTorch version the README links to. Before cloning, read the top of the README, confirm the environment file matches the Python version you can install, and check whether the notebook you want is already covered by the newer repositories.

Official sources

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