schuetoliver
/
handson-ml
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Simplify the installation instructions

main
Aurélien Geron 2019-12-16 23:11:50 +08:00
parent 8729aeb196
commit b6be3eca67
2 changed files with 41 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
INSTALL.md
View File

@ -1,7 +1,7 @@
# Installation # Installation
## Download this repository ## Download this repository
To install this repository and run the Jupyter notebooks on your machine, you will first need git, which you probably already have. Open a terminal and type `git` to check. If you do not have git, you can download it from [git-scm.com](https://git-scm.com/). To install this repository and run the Jupyter notebooks on your machine, you will first need git, which you may already have. Open a terminal and type `git` to check. If you do not have git, you can download it from [git-scm.com](https://git-scm.com/).
Next, clone this repository by opening a terminal and typing the following commands: Next, clone this repository by opening a terminal and typing the following commands:
@ -11,34 +11,42 @@ Next, clone this repository by opening a terminal and typing the following comma
If you do not want to install git, you can instead download [master.zip](https://github.com/ageron/handson-ml2/archive/master.zip), unzip it, rename the resulting directory to `handson-ml2` and move it to your development directory. If you do not want to install git, you can instead download [master.zip](https://github.com/ageron/handson-ml2/archive/master.zip), unzip it, rename the resulting directory to `handson-ml2` and move it to your development directory.
## Python 3 and the required libraries ## Install Anaconda
Next, you will need Python 3.6+ and a bunch of Python libraries. The simplest way to install these is to use Anaconda, which is a great cross-platform Python distribution for scientific computing. It comes bundled with many scientific libraries, including NumPy, Pandas, Matplotlib, Scikit-Learn and much more, so it's quite a large installation. If you choose to [download and install Anaconda](https://www.anaconda.com/distribution/), just make sure to install the Python 3 version. If you prefer a lighter weight Anaconda distribution, you can [install Miniconda](https://docs.conda.io/en/latest/miniconda.html), which contains the bare minimum to run the `conda` packaging tool. Next, you will need Python 3.6 or 3.7 and a bunch of Python libraries. The simplest way to install these is to use Anaconda, which is a great cross-platform Python distribution for scientific computing. It comes bundled with many scientific libraries, including NumPy, Pandas, Matplotlib, Scikit-Learn and much more, so it's quite a large installation. If you choose to [download and install Anaconda](https://www.anaconda.com/distribution/), just make sure to install the Python 3 version. If you prefer a lighter weight Anaconda distribution, you can [install Miniconda](https://docs.conda.io/en/latest/miniconda.html), which contains the bare minimum to run the `conda` packaging tool.
Once Anaconda or Miniconda is installed, open a terminal and run the following command. It will create a new `conda` enviromnent containing every library you will need (by default, the environment will be named `tf2`, but you can choose another name using the `-n` option): Once Anaconda or miniconda is installed, then run the following command to update the conda packaging tool to the latest version:
$ conda env create -f environment.yml $ conda update -n base -c defaults conda
> **Note**: if you don't like Anaconda for some reason, then you can install Python 3 and use pip to install the required libraries manually (this is not recommended, unless you know what you are doing).
## Install the GPU Driver and Libraries
If you have a TensorFlow-compatible GPU card (NVidia card with Compute Capability ≥ 3.5), and you want TensorFlow to use it, then you should download the latest driver for your card from [nvidia.com](https://www.nvidia.com/Download/index.aspx?lang=en-us) and install it. You will also need NVidia's CUDA and cuDNN libraries, but the good news is that they will be installed automatically when you install the tensorflow-gpu package from Anaconda. However, if you don't use Anaconda, you will have to install them manually. If you hit any roadblock, see TensorFlow's [GPU installation instructions](https://tensorflow.org/install/gpu) for more details.
If you want to use a GPU then you should also edit environment.yml (or environment-windows.yml if you're on Windows), located at the root of the handson-ml2 project, replace tensorflow=2.0.0 with tensorflow-gpu=2.0.0, and replace tensorflow-serving-api==2.0.0 with tensorflow-serving-api-gpu==2.0.0. This will not be needed anymore when TensorFlow 2.1 is released.
## Create the tf2 Environment
Next, make sure you're in the handson-ml2 directory and run the following command. It will create a new `conda` enviromnent containing every library you will need to run all the notebooks (by default, the environment will be named `tf2`, but you can choose another name using the `-n` option):
$ conda env create -f environment.yml # or environment-windows.yml on Windows
Next, activate the new environment: Next, activate the new environment:
$ conda activate tf2 $ conda activate tf2
> **Note**: if you don't like Anaconda for some reason, then you can install Python 3 and the required libraries manually (this is not recommended, unless you know what you are doing). For this, go through the [Manual Python Installation](#manual-python-installation) section then come back here and continue to the next sections. ## Windows
If you're on Windows, and you want to go through chapter 18 on Reinforcement Learning, then you will also need to run the following command. It installs a Windows-compatible fork of the atari-py library.
## Using a GPU $ pip install --no-index -f https://github.com/Kojoley/atari-py/releases atari_py
If you have a TensorFlow-compatible GPU card (NVidia card with Compute Capability ≥ 3.5), and you want TensorFlow to use it, then you should follow TensorFlow's [GPU installation instructions](https://tensorflow.org/install/gpu) to install the driver and libraries such as CUDA and CuDNN.
Also make sure to replace the `tensorflow` library with the `tensorflow-gpu` library (this will no longer be needed starting in TensorFlow 2.1):
$ pip uninstall tensorflow > **Warning**: TensorFlow Transform (used in chapter 13) and TensorFlow-AddOns (used in chapter 16) are not yet available on Windows, but the TensorFlow team is working on it.
$ pip install -U tensorflow-gpu
## Reinforcement Learning Chapter Requirements
If you want to go through chapter 18 on Reinforcement Learning, you will need to [install OpenAI gym](https://gym.openai.com/docs) and its dependencies for Atari simulations.
## Starting Jupyter ## Start Jupyter
You're almost there! You just need to register the `tf2` conda environment to Jupyter. The notebooks in this project will defaut to the environment named `python3`, so it's best to register this environment using the name `python3` (if you prefer to use another name, you will have to select it in the "Kernel > Change kernel..." menu in Jupyter every time you open a notebook): You're almost there! You just need to register the `tf2` conda environment to Jupyter. The notebooks in this project will defaut to the environment named `python3`, so it's best to register this environment using the name `python3` (if you prefer to use another name, you will have to select it in the "Kernel > Change kernel..." menu in Jupyter every time you open a notebook):
$ conda activate tf2
$ python3 -m ipykernel install --user --name=python3 $ python3 -m ipykernel install --user --name=python3
And that's it! You can now start Jupyter like this: And that's it! You can now start Jupyter like this:
@ -55,48 +63,3 @@ When you're done with Jupyter, you can close it by typing Ctrl-C in the Terminal
$ cd handson-ml2 $ cd handson-ml2
$ conda activate tf2 $ conda activate tf2
$ jupyter notebook $ jupyter notebook
## Manual Python Installation
**Not recommended**: use Anaconda or Miniconda instead, unless you know what you're doing.
First, you will need Python 3.6 or 3.7. Some systems have it preinstalled. You can check by running the following command:
$ python3 --version
If you have Python 3.6 or 3.7 already installed, that's great. If not, on Windows or MacOSX, you can just download it from [python.org](https://www.python.org/downloads/). On MacOSX, you can alternatively use [MacPorts](https://www.macports.org/) or [Homebrew](https://brew.sh/). If you are using Python 3.6+ on MacOSX, you need to run the following command to install the `certifi` package of certificates because Python 3.6+ on MacOSX has no certificates to validate SSL connections (see this [StackOverflow question](https://stackoverflow.com/questions/27835619/urllib-and-ssl-certificate-verify-failed-error)):
$ /Applications/Python\ 3.6/Install\ Certificates.command # or Python 3.7
On Linux, unless you know what you are doing, you should probably use your system's packaging system. For example, on Debian or Ubuntu, type:
$ sudo apt-get update
$ sudo apt-get install python3 python3-pip
Next, you will need to install the Python libraries that are necessary for this project, in particular NumPy, Matplotlib, Pandas, Jupyter and TensorFlow (and a few others). For this, you can either use Python's integrated packaging system, pip, or you may prefer to use your system's own packaging system (if available, e.g. on Linux, or on MacOSX when using MacPorts or Homebrew). The advantage of using pip is that it is easy to create multiple isolated Python environments with different libraries and different library versions (e.g. one environment for each project). The advantage of using your system's packaging system is that there is less risk of having conflicts between your Python libraries and your system's other packages.
In this section, we will look at how to use pip. First, make sure you have the latest version of pip installed:
$ python3 -m pip install --user -U pip setuptools
The `--user` option will install the latest version of pip only for the current user. If you prefer to install it system wide (i.e. for all users), you must have administrator rights (e.g. use `sudo python3 -m pip` instead of `python3 -m pip` on Linux), and you should remove the `--user` option. The same is true of the command below that uses the `--user` option.
Next, you can optionally create an isolated environment. This is recommended as it makes it possible to have a different environment for each project (e.g., one for this project), with potentially very different libraries, and different versions:
$ python3 -m pip install --user -U virtualenv
$ python3 -m virtualenv -p `which python3` env
This creates a new directory called `env` in the current directory, containing an isolated Python environment based on Python 3. If you installed multiple versions of Python 3 on your system, you can replace `` `which python3` `` with the path to the Python executable you prefer to use.
Now you must activate this environment. You will need to run this command every time you want to use this environment.
$ source ./env/bin/activate
On Windows, the command is slightly different:
$ .\env\Scripts\activate
Next, use pip to install the required python packages. If you are not using virtualenv, you should add the `--user` option (alternatively you could install the libraries system-wide, but this will probably require administrator rights, e.g. using `sudo python3` instead of `python3` on Linux).
$ python3 -m pip install -U -r requirements.txt
Great! You now have Python 3.6 or 3.7 installed with all the required libraries. You can now resume the installation instructions starting at the [Using a GPU](#using-a-gpu) section above. However, you will need to replace the `pip` command with `python3 -m pip`, and replace `conda activate tf2` with `source ./env/bin/activate` (or `.\env\Scripts\activate` on Windows).

23
README.md
View File

@ -38,17 +38,30 @@ Read the [Docker instructions](https://github.com/ageron/handson-ml2/tree/master
### Want to install this project on your own machine? ### Want to install this project on your own machine?
If you have [Anaconda](https://www.anaconda.com/distribution/) (or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)) and git installed, then this project and its dependencies can be installed quite simply. Open a terminal and run the following commands (do not type the first `$` signs on each line, they just indicate that these are terminal commands): Start by installing [Anaconda](https://www.anaconda.com/distribution/) (or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)), [git](https://git-scm.com/downloads), and if you have a TensorFlow-compatible GPU, install the [GPU driver](https://www.nvidia.com/Download/index.aspx).
Next, clone this project by opening a terminal and typing the following commands (do not type the first `$` signs on each line, they just indicate that these are terminal commands):
$ git clone https://github.com/ageron/handson-ml2.git $ git clone https://github.com/ageron/handson-ml2.git
$ cd handson-ml2 $ cd handson-ml2
$ # Read `environment.yml` if you want to use a GPU.
$ conda env create -f environment.yml If you want to use a GPU, then edit `environment.yml` (or `environment-windows.yml` on Windows) and replace `tensorflow=2.0.0` with `tensorflow-gpu=2.0.0`. Also replace `tensorflow-serving-api==2.0.0` with `tensorflow-serving-api-gpu==2.0.0`.
Next, run the following commands:
$ conda env create -f environment.yml # or environment-windows.yml on Windows
$ conda activate tf2 $ conda activate tf2
$ python3 -m ipykernel install --user --name=python3 $ python -m ipykernel install --user --name=python3
Then if you're on Windows, run the following command:
$ pip install --no-index -f https://github.com/Kojoley/atari-py/releases atari_py
Finally, start Jupyter:
$ jupyter notebook $ jupyter notebook
If you prefer to install Python and the required libraries manually, or if you need further instructions, read the [detailed installation instructions](INSTALL.md). If you need further instructions, read the [detailed installation instructions](INSTALL.md).
## Contributors ## Contributors
I would like to thank everyone who contributed to this project, either by providing useful feedback, filing issues or submitting Pull Requests. Special thanks go to Haesun Park who helped on some of the exercise solutions, and to Steven Bunkley and Ziembla who created the `docker` directory. I would like to thank everyone who contributed to this project, either by providing useful feedback, filing issues or submitting Pull Requests. Special thanks go to Haesun Park who helped on some of the exercise solutions, and to Steven Bunkley and Ziembla who created the `docker` directory.