# ageron/handson-ml: the first-edition notebooks, and why the README now points elsewhere > The original Hands-On Machine Learning notebook repository is a 2017-era teaching set pinned to TensorFlow 1.15.5 and scikit-learn 0.24.1. It still installs, but the README's first line sends new readers to the third edition and the PyTorch version instead. **ageron/handson-ml** — ⛔️ DEPRECATED – See https://github.com/ageron/handson-ml3 or handson-mlp instead. - Repository: https://github.com/ageron/handson-ml - Stars: 25,604 · Forks: 12,718 - Language: Jupyter Notebook - License: Apache-2.0 - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/ageron-handson-ml ## What this repository is, and who it was written for This is the companion code for the first edition of Hands-On Machine Learning with Scikit-Learn and TensorFlow, published in 2017. The README describes it plainly: "This project is for the first edition, which is now outdated (it came out in 2017)." Sixteen numbered notebooks run from 01_the_machine_learning_landscape.ipynb through 16_reinforcement_learning.ipynb, with a handful of extra notebooks on autodiff, capsule networks, gradient descent comparison and TensorFlow reproducibility, plus tool notebooks for NumPy, pandas and Matplotlib. The audience is a reader working through that specific book. The notebooks contain the example code and the solutions to the exercises, so the repository is a companion rather than a standalone course. If you have the first edition on your desk, the chapter numbering lines up. If you do not, you are reading someone else's exercise answers without the surrounding explanation, and the README's own redirect suggests the author would rather you start with the third edition. The repository is not archived, and the last push was on 2026-05-19. That is a recent commit, but it sits alongside a README that opens with a deprecation banner and a link to handson-ml3 and handson-mlp. A recent push on a deprecated teaching repository most likely means small fixes, not a revived dependency set. The pinned versions in requirements.txt tell the real story. ## The version pins are the whole story requirements.txt is explicit about what this code expects. The core scientific stack is frozen at numpy==1.22.0, pandas==1.2.2, scipy==1.6.0 and matplotlib==3.3.4. The machine learning layer is scikit-learn==0.24.1. The deep learning layer is tensorflow==1.15.5, with tensorflow-gpu==1.15.5 named as the GPU alternative, and tensorboard==1.15.0. Chapter 16 additionally needs gym[atari,Box2D]==0.18.0. TensorFlow 1.15 was the last release of the 1.x line. Code written against it uses tf.placeholder, sessions and graph construction, none of which is the default style in TensorFlow 2. That is not a small stylistic gap. A reader who learns from chapters 09 through 14 here is learning an API that no longer matches current TensorFlow documentation, and there is no migration layer in the repository to bridge the two. The scikit-learn pin matters less but still matters. Version 0.24.1 predates several rounds of estimator changes, so a reader who installs a current scikit-learn and runs chapter 04 or 07 may hit parameter names that have moved. The repository does not attempt to paper over this. It pins instead, which is the honest choice for a book companion: the code matches the printed text, and the environment is reproducible as long as the old wheels remain installable. ## Installing it locally and opening the first notebook The README's local path assumes Anaconda or Miniconda, git, and a GPU driver plus CUDA and cuDNN if you want GPU support. It does not use pip for the environment itself; the environment comes from environment.yml, and the conda environment is named tf1. Clone and create it first: ```bash git clone https://github.com/ageron/handson-ml.git cd handson-ml conda env create -f environment.yml conda activate tf1 ``` After activation, register the environment as a Jupyter kernel under the name python3, then start Jupyter: ```bash python -m ipykernel install --user --name=python3 jupyter notebook ``` Jupyter opens in your browser with the repository root as the working directory. Opening 02_end_to_end_machine_learning_project.ipynb is the natural first run, because it is the chapter that exercises the dataset download path. The README's FAQ flags the most common failure here: load_housing_data() raises an error unless fetch_housing_data() has been called first, and an HTTP error usually means the notebook cell was edited rather than run as written. The README also offers routes that skip installation entirely. Opening the repository in Colab, Binder or Deepnote runs the notebooks in a temporary environment, and the README warns that anything you do there is deleted after a while. For reading rather than running, nbviewer renders the notebooks; the README notes that GitHub's own viewer works too but is slower and sometimes renders the math equations incorrectly. There is a docker directory with separate instructions if you prefer a container, and INSTALL.md holds the longer version of the local setup. ## Python 3.7, SSL errors, and other environment friction The README recommends Python 3.7 and says the conda environment above gives you that version. It adds that most code works with other Python 3 versions, but that some libraries do not support Python 3.8 or 3.9 yet, which is why 3.7 is the recommendation. Read that sentence as a hard constraint rather than a preference. If your machine already runs a newer Python and you try to assemble the stack by hand instead of through environment.yml, you are on your own. The FAQ covers two other failure modes. On macOS you may hit an SSL certificate verification error during dataset downloads; the README points to a StackOverflow question and gives two fixes, running /Applications/Python\ 3.7/Install\ Certificates.command for a python.org install, or sudo port install curl-ca-bundle for a MacPorts install. Both are environment fixes, not repository fixes. Updating the project and updating the Python libraries are both deferred to INSTALL.md, which means the README does not document the upgrade procedure inline. That is a reasonable split for a long document, but it does mean the answer to "how do I move to newer libraries" is not on the front page, and the pinned requirements.txt suggests the intended answer is that you do not. ## Where this repository is the wrong tool The clearest case against it is the one the author makes. The README's opening line announces that the third edition is available, along with a PyTorch version and many translations, and then states that this project is for the first edition and is outdated. A reader who wants to learn machine learning today and has no attachment to the 2017 text should follow that link rather than clone this repository. The second case is anyone targeting a current TensorFlow. Nothing in the repository teaches TensorFlow 2 idioms, and the pinned tensorflow==1.15.5 will not run on a modern Python without a compatible environment. If your goal is to build something with today's TensorFlow, the notebooks here are a historical reference, not a tutorial. The third case is a reader who wants a self-contained course. This is a book companion. The notebooks assume you have the printed chapters, and the exercise solutions only make sense in that context. The repository also does not document rollback or a supported upgrade path for the pinned stack; INSTALL.md is where update questions are routed, and the README does not summarize what it says. ## Alternatives and the actual difference in approach The README names two successors directly. ageron/handson-ml3 is the third edition of the same book, and ageron/handson-mlp is a PyTorch version. The difference is not cosmetic. The third edition moves the deep learning chapters to Keras on TensorFlow 2, which means the graph-and-session style in chapters 09 through 14 here is replaced by model-building APIs. A reader who learns from handson-ml3 is learning an API that current documentation still describes. handson-mlp changes the framework rather than the edition. If your interest is PyTorch, the TensorFlow chapters here are of limited use, and the PyTorch version is the repository the README points to. The RELATED SEARCHES list shows people looking for exactly this split, with queries about the third edition, the PyTorch edition, and a fourth edition. Only the first two are answered by anything in this repository's README. For the scikit-learn half of the book, the gap is narrower. Chapters 01 through 08 are largely scikit-learn material, and the concepts survive the version change even if some parameter names do not. A reader who wants the classical algorithms and is willing to run an old scikit-learn can still get value here, but the same material exists in the newer edition with current pins. ## Licence, maintenance and what upgrading actually costs The repository is Apache-2.0. For a teaching repository that is a permissive choice: you can reuse the notebook code in your own work, including commercially, provided you keep the licence and attribution intact. The notebooks also reproduce material tied to a published O'Reilly book, so the code licence and the right to redistribute the book's prose are separate questions. Nothing here gives you the book text. If you plan to republish substantial portions of the notebooks, read the LICENSE file rather than assuming the Apache grant covers the book's explanatory content. Maintenance status is mixed and worth stating precisely. The repository is not archived, and the last push was on 2026-05-19, which is recent. But the README describes the project as outdated, and the dependency pins are frozen at a TensorFlow line that ended with 1.15. A recent push does not change the fact that the environment is a 2017-era snapshot. The upgrade cost is the real cost. Moving the notebooks to TensorFlow 2 is not a version bump; it is a rewrite of the deep learning chapters, which is presumably why the third edition exists as a separate repository rather than a branch. For the scikit-learn chapters the work is smaller but still manual, since the pins in requirements.txt are the only compatibility statement the repository makes. ## Conclusion Adopt this repository only if you specifically need the 2017 first-edition text, its TensorFlow 1.x code, or the exercise solutions as they were written then. Do not adopt it as a starting point for learning ML in 2026: the README itself calls the project outdated and redirects to ageron/handson-ml3 and ageron/handson-mlp, and the pinned tensorflow==1.15.5 has no path forward on current Python. Before cloning, check whether the chapter you want exists in the third-edition repository, and confirm your Python version against the README's recommendation of Python 3.7, since the pinned libraries do not support 3.8 or 3.9 according to the FAQ. ## FAQ ### What is hands-on machine learning? In this repository's context it is the first edition of the O'Reilly book Hands-On Machine Learning with Scikit-Learn and TensorFlow, published in 2017. The repository holds the example code and exercise solutions that accompany that book, in sixteen numbered notebooks. ### What are the main 3 types of ML models? The repository does not answer this directly in the README; the material that covers it is the chapter notebooks, starting with 01_the_machine_learning_landscape.ipynb. The README only lists the notebook filenames, so the classification itself is in the notebook content, not the front page. ### Is handson-ml still maintained? The repository is not archived and the last push was on 2026-05-19, but the README states that the project is for the first edition and is now outdated, and it directs readers to handson-ml3 and handson-mlp. The dependency pins in requirements.txt are frozen at tensorflow==1.15.5 and scikit-learn==0.24.1. ### Which Python version does handson-ml need? The README recommends Python 3.7 and says the conda environment in environment.yml provides it. It adds that some libraries do not support Python 3.8 or 3.9 yet, which is the stated reason for the recommendation. ### Why does load_housing_data() fail in handson-ml? The README's FAQ says you must call fetch_housing_data() before load_housing_data(). If the error is an HTTP error, the README advises running the exact code from the notebook, and checking your network configuration if it persists. ### Can I run handson-ml without installing anything? Yes. The README lists Colab, Binder and Deepnote as temporary environments, and nbviewer for reading notebooks without executing them. It warns that the temporary services delete your work after a while, so download anything you want to keep. ## Sources - [ageron/handson-ml on GitHub](https://github.com/ageron/handson-ml) - [Issues](https://github.com/ageron/handson-ml/issues) - [License: Apache-2.0](https://github.com/ageron/handson-ml/blob/master/LICENSE) - [README](https://github.com/ageron/handson-ml/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ageron-handson-ml