Skip to content

Commit 1f0d212

Browse files
anupambhatnagarChris Elion
anupambhatnagar
authored and
Chris Elion
committed
Conda docker docs (#2982)
* restoring conda and docker documentation
1 parent b9100d9 commit 1f0d212

File tree

3 files changed

+532
-8
lines changed

3 files changed

+532
-8
lines changed

‎docs/Installation-Windows.md‎

Lines changed: 354 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,354 @@
1+
# Installing ML-Agents Toolkit for Windows (Deprecated)
2+
3+
Note: We no longer use this guide ourselves and so it may not work correctly. We've decided to
4+
keep it up just in case it is helpful to you.
5+
6+
The ML-Agents toolkit supports Windows 10. While it might be possible to run the
7+
ML-Agents toolkit using other versions of Windows, it has not been tested on
8+
other versions. Furthermore, the ML-Agents toolkit has not been tested on a
9+
Windows VM such as Bootcamp or Parallels.
10+
11+
To use the ML-Agents toolkit, you install Python and the required Python
12+
packages as outlined below. This guide also covers how set up GPU-based training
13+
(for advanced users). GPU-based training is not currently required for the
14+
ML-Agents toolkit. However, training on a GPU might be required by future
15+
versions and features.
16+
17+
## Step 1: Install Python via Anaconda
18+
19+
[Download](https://www.anaconda.com/download/#windows) and install Anaconda for
20+
Windows. By using Anaconda, you can manage separate environments for different
21+
distributions of Python. Python 3.6.1 or higher is required as we no longer support
22+
Python 2. In this guide, we are using Python version 3.6 and Anaconda version
23+
5.1
24+
([64-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86_64.exe)
25+
or [32-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86.exe)
26+
direct links).
27+
28+
<p align="center">
29+
<img src="images/anaconda_install.PNG"
30+
alt="Anaconda Install"
31+
width="500" border="10" />
32+
</p>
33+
34+
We recommend the default _advanced installation options_. However, select the
35+
options appropriate for your specific situation.
36+
37+
<p align="center">
38+
<img src="images/anaconda_default.PNG" alt="Anaconda Install" width="500" border="10" />
39+
</p>
40+
41+
After installation, you must open __Anaconda Navigator__ to finish the setup.
42+
From the Windows search bar, type _anaconda navigator_. You can close Anaconda
43+
Navigator after it opens.
44+
45+
If environment variables were not created, you will see error "conda is not
46+
recognized as internal or external command" when you type `conda` into the
47+
command line. To solve this you will need to set the environment variable
48+
correctly.
49+
50+
Type `environment variables` in the search bar (this can be reached by hitting
51+
the Windows key or the bottom left Windows button). You should see an option
52+
called __Edit the system environment variables__.
53+
54+
<p align="center">
55+
<img src="images/edit_env_var.png"
56+
alt="edit env variables"
57+
width="250" border="10" />
58+
</p>
59+
60+
From here, click the __Environment Variables__ button. Double click "Path" under
61+
__System variable__ to edit the "Path" variable, click __New__ to add the
62+
following new paths.
63+
64+
```console
65+
%UserProfile%\Anaconda3\Scripts
66+
%UserProfile%\Anaconda3\Scripts\conda.exe
67+
%UserProfile%\Anaconda3
68+
%UserProfile%\Anaconda3\python.exe
69+
```
70+
71+
## Step 2: Setup and Activate a New Conda Environment
72+
73+
You will create a new [Conda environment](https://conda.io/docs/) to be used
74+
with the ML-Agents toolkit. This means that all the packages that you install
75+
are localized to just this environment. It will not affect any other
76+
installation of Python or other environments. Whenever you want to run
77+
ML-Agents, you will need activate this Conda environment.
78+
79+
To create a new Conda environment, open a new Anaconda Prompt (_Anaconda Prompt_
80+
in the search bar) and type in the following command:
81+
82+
```sh
83+
conda create -n ml-agents python=3.6
84+
```
85+
86+
You may be asked to install new packages. Type `y` and press enter _(make sure
87+
you are connected to the Internet)_. You must install these required packages.
88+
The new Conda environment is called ml-agents and uses Python version 3.6.
89+
90+
<p align="center">
91+
<img src="images/conda_new.PNG" alt="Anaconda Install" width="500" border="10" />
92+
</p>
93+
94+
To use this environment, you must activate it. _(To use this environment In the
95+
future, you can run the same command)_. In the same Anaconda Prompt, type in the
96+
following command:
97+
98+
```sh
99+
activate ml-agents
100+
```
101+
102+
You should see `(ml-agents)` prepended on the last line.
103+
104+
Next, install `tensorflow`. Install this package using `pip` - which is a
105+
package management system used to install Python packages. Latest versions of
106+
TensorFlow won't work, so you will need to make sure that you install version
107+
1.7.1. In the same Anaconda Prompt, type in the following command _(make sure
108+
you are connected to the Internet)_:
109+
110+
```sh
111+
pip install tensorflow==1.7.1
112+
```
113+
114+
## Step 3: Install Required Python Packages
115+
116+
The ML-Agents toolkit depends on a number of Python packages. Use `pip` to
117+
install these Python dependencies.
118+
119+
If you haven't already, clone the ML-Agents Toolkit Github repository to your
120+
local computer. You can do this using Git ([download
121+
here](https://git-scm.com/download/win)) and running the following commands in
122+
an Anaconda Prompt _(if you open a new prompt, be sure to activate the ml-agents
123+
Conda environment by typing `activate ml-agents`)_:
124+
125+
```sh
126+
git clone https://github.com/Unity-Technologies/ml-agents.git
127+
```
128+
129+
If you don't want to use Git, you can always directly download all the files
130+
[here](https://github.com/Unity-Technologies/ml-agents/archive/master.zip).
131+
132+
The `UnitySDK` subdirectory contains the Unity Assets to add to your projects.
133+
It also contains many [example environments](Learning-Environment-Examples.md)
134+
to help you get started.
135+
136+
The `ml-agents` subdirectory contains a Python package which provides deep reinforcement
137+
learning trainers to use with Unity environments.
138+
139+
The `ml-agents-envs` subdirectory contains a Python API to interface with Unity, which
140+
the `ml-agents` package depends on.
141+
142+
The `gym-unity` subdirectory contains a package to interface with OpenAI Gym.
143+
144+
Keep in mind where the files were downloaded, as you will need the
145+
trainer config files in this directory when running `mlagents-learn`.
146+
Make sure you are connected to the Internet and then type in the Anaconda
147+
Prompt:
148+
149+
```console
150+
pip install mlagents
151+
```
152+
153+
This will complete the installation of all the required Python packages to run
154+
the ML-Agents toolkit.
155+
156+
Sometimes on Windows, when you use pip to install certain Python packages, the pip will get stuck when trying to read the cache of the package. If you see this, you can try:
157+
158+
```console
159+
pip install mlagents --no-cache-dir
160+
```
161+
162+
This `--no-cache-dir` tells the pip to disable the cache.
163+
164+
### Installing for Development
165+
166+
If you intend to make modifications to `ml-agents` or `ml-agents-envs`, you should install
167+
the packages from the cloned repo rather than from PyPi. To do this, you will need to install
168+
`ml-agents` and `ml-agents-envs` separately.
169+
170+
In our example, the files are located in `C:\Downloads`. After you have either
171+
cloned or downloaded the files, from the Anaconda Prompt, change to the ml-agents
172+
subdirectory inside the ml-agents directory:
173+
174+
```console
175+
cd C:\Downloads\ml-agents
176+
```
177+
178+
From the repo's main directory, now run:
179+
180+
```console
181+
cd ml-agents-envs
182+
pip install -e .
183+
cd ..
184+
cd ml-agents
185+
pip install -e .
186+
```
187+
188+
Running pip with the `-e` flag will let you make changes to the Python files directly and have those
189+
reflected when you run `mlagents-learn`. It is important to install these packages in this order as the
190+
`mlagents` package depends on `mlagents_envs`, and installing it in the other
191+
order will download `mlagents_envs` from PyPi.
192+
193+
## (Optional) Step 4: GPU Training using The ML-Agents Toolkit
194+
195+
GPU is not required for the ML-Agents toolkit and won't speed up the PPO
196+
algorithm a lot during training(but something in the future will benefit from
197+
GPU). This is a guide for advanced users who want to train using GPUs.
198+
Additionally, you will need to check if your GPU is CUDA compatible. Please
199+
check Nvidia's page [here](https://developer.nvidia.com/cuda-gpus).
200+
201+
Currently for the ML-Agents toolkit, only CUDA v9.0 and cuDNN v7.0.5 is supported.
202+
203+
### Install Nvidia CUDA toolkit
204+
205+
[Download](https://developer.nvidia.com/cuda-toolkit-archive) and install the
206+
CUDA toolkit 9.0 from Nvidia's archive. The toolkit includes GPU-accelerated
207+
libraries, debugging and optimization tools, a C/C++ (Step Visual Studio 2017)
208+
compiler and a runtime library and is needed to run the ML-Agents toolkit. In
209+
this guide, we are using version
210+
[9.0.176](https://developer.nvidia.com/compute/cuda/9.0/Prod/network_installers/cuda_9.0.176_win10_network-exe)).
211+
212+
Before installing, please make sure you __close any running instances of Unity
213+
or Visual Studio__.
214+
215+
Run the installer and select the Express option. Note the directory where you
216+
installed the CUDA toolkit. In this guide, we installed in the directory
217+
`C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v9.0`
218+
219+
### Install Nvidia cuDNN library
220+
221+
[Download](https://developer.nvidia.com/cudnn) and install the cuDNN library
222+
from Nvidia. cuDNN is a GPU-accelerated library of primitives for deep neural
223+
networks. Before you can download, you will need to sign up for free to the
224+
Nvidia Developer Program.
225+
226+
<p align="center">
227+
<img src="images/cuDNN_membership_required.png"
228+
alt="cuDNN membership required"
229+
width="500" border="10" />
230+
</p>
231+
232+
Once you've signed up, go back to the cuDNN
233+
[downloads page](https://developer.nvidia.com/cudnn).
234+
You may or may not be asked to fill out a short survey. When you get to the list
235+
cuDNN releases, __make sure you are downloading the right version for the CUDA
236+
toolkit you installed in Step 1.__ In this guide, we are using version 7.0.5 for
237+
CUDA toolkit version 9.0
238+
([direct link](https://developer.nvidia.com/compute/machine-learning/cudnn/secure/v7.0.5/prod/9.0_20171129/cudnn-9.0-windows10-x64-v7)).
239+
240+
After you have downloaded the cuDNN files, you will need to extract the files
241+
into the CUDA toolkit directory. In the cuDNN zip file, there are three folders
242+
called `bin`, `include`, and `lib`.
243+
244+
<p align="center">
245+
<img src="images/cudnn_zip_files.PNG"
246+
alt="cuDNN zip files"
247+
width="500" border="10" />
248+
</p>
249+
250+
Copy these three folders into the CUDA toolkit directory. The CUDA toolkit
251+
directory is located at
252+
`C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v9.0`
253+
254+
<p align="center">
255+
<img src="images/cuda_toolkit_directory.PNG"
256+
alt="cuda toolkit directory"
257+
width="500" border="10" />
258+
</p>
259+
260+
### Set Environment Variables
261+
262+
You will need to add one environment variable and two path variables.
263+
264+
To set the environment variable, type `environment variables` in the search bar
265+
(this can be reached by hitting the Windows key or the bottom left Windows
266+
button). You should see an option called __Edit the system environment
267+
variables__.
268+
269+
<p align="center">
270+
<img src="images/edit_env_var.png"
271+
alt="edit env variables"
272+
width="250" border="10" />
273+
</p>
274+
275+
From here, click the __Environment Variables__ button. Click __New__ to add a
276+
new system variable _(make sure you do this under __System variables__ and not
277+
User variables_.
278+
279+
<p align="center">
280+
<img src="images/new_system_variable.PNG"
281+
alt="new system variable"
282+
width="500" border="10" />
283+
</p>
284+
285+
For __Variable Name__, enter `CUDA_HOME`. For the variable value, put the
286+
directory location for the CUDA toolkit. In this guide, the directory location
287+
is `C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v9.0`. Press __OK__ once.
288+
289+
<p align="center">
290+
<img src="images/system_variable_name_value.PNG"
291+
alt="system variable names and values"
292+
width="500" border="10" />
293+
</p>
294+
295+
To set the two path variables, inside the same __Environment Variables__ window
296+
and under the second box called __System Variables__, find a variable called
297+
`Path` and click __Edit__. You will add two directories to the list. For this
298+
guide, the two entries would look like:
299+
300+
```console
301+
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v9.0\lib\x64
302+
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v9.0\extras\CUPTI\libx64
303+
```
304+
305+
Make sure to replace the relevant directory location with the one you have
306+
installed. _Please note that case sensitivity matters_.
307+
308+
<p align="center">
309+
<img src="images/path_variables.PNG"
310+
alt="Path variables"
311+
width="500" border="10" />
312+
</p>
313+
314+
### Install TensorFlow GPU
315+
316+
Next, install `tensorflow-gpu` using `pip`. You'll need version 1.7.1. In an
317+
Anaconda Prompt with the Conda environment ml-agents activated, type in the
318+
following command to uninstall TensorFlow for cpu and install TensorFlow
319+
for gpu _(make sure you are connected to the Internet)_:
320+
321+
```sh
322+
pip uninstall tensorflow
323+
pip install tensorflow-gpu==1.7.1
324+
```
325+
326+
Lastly, you should test to see if everything installed properly and that
327+
TensorFlow can identify your GPU. In the same Anaconda Prompt, open Python
328+
in the Prompt by calling:
329+
330+
```sh
331+
python
332+
```
333+
334+
And then type the following commands:
335+
336+
```python
337+
import tensorflow as tf
338+
339+
sess = tf.Session(config=tf.ConfigProto(log_device_placement=True))
340+
```
341+
342+
You should see something similar to:
343+
344+
```console
345+
Found device 0 with properties ...
346+
```
347+
348+
## Acknowledgments
349+
350+
We would like to thank
351+
[Jason Weimann](https://unity3d.college/2017/10/25/machine-learning-in-unity3d-setting-up-the-environment-tensorflow-for-agentml-on-windows-10/)
352+
and
353+
[Nitish S. Mutha](http://blog.nitishmutha.com/tensorflow/2017/01/22/TensorFlow-with-gpu-for-windows.html)
354+
for writing the original articles which were used to create this guide.

‎docs/Readme.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,6 @@
4444
* [Training with LSTM](Feature-Memory.md)
4545
* [Training Generalized Reinforcement Learning Agents](Training-Generalized-Reinforcement-Learning-Agents.md)
4646

47-
### Cloud Training (Deprecated)
48-
Here are the cloud training set-up guides for Azure and AWS. We no longer use them ourselves and
49-
so they may not be work correctly. We've decided to keep them up just in case they are helpful to
50-
you.
51-
52-
* [Training on the Cloud with Amazon Web Services](Training-on-Amazon-Web-Service.md)
53-
* [Training on the Cloud with Microsoft Azure](Training-on-Microsoft-Azure.md)
54-
5547
## Inference
5648

5749
* [Unity Inference Engine](Unity-Inference-Engine.md)
@@ -68,3 +60,12 @@ you.
6860
* [API Reference](API-Reference.md)
6961
* [How to use the Python API](Python-API.md)
7062
* [Wrapping Learning Environment as a Gym (+Baselines/Dopamine Integration)](../gym-unity/README.md)
63+
64+
## Deprecated Docs
65+
We no longer use them ourselves and so they may not be up-to-date.
66+
We've decided to keep them up just in case they are helpful to you.
67+
68+
* [Training on the Cloud with Amazon Web Services](Training-on-Amazon-Web-Service.md)
69+
* [Training on the Cloud with Microsoft Azure](Training-on-Microsoft-Azure.md)
70+
* [Using Docker](Using-Docker.md)
71+
* [Installation-Windows](Installation-Windows.md)

0 commit comments

Comments
 (0)