ml-agents/docs/Installation.md

Installation

The ML-Agents Toolkit contains several components:

• Unity package (com.unity.ml-agents) contains the Unity C# SDK that will be integrated into your Unity scene.
• Three Python packages:
  • mlagents contains the machine learning algorithms that enables you to train behaviors in your Unity scene. Most users of ML-Agents will only need to directly install mlagents.
  • mlagents_envs contains a Python API to interact with a Unity scene. It is a foundational layer that facilitates data messaging between Unity scene and the Python machine learning algorithms. Consequently, mlagents depends on mlagents_envs.
  • gym_unity provides a Python-wrapper for your Unity scene that supports the OpenAI Gym interface.
• Unity Project that contains several example environments that highlight the various features of the toolkit to help you get started.

Consequently, to install and use ML-Agents you will need to:

• Install Unity (2018.4 or later)
• Install Python (3.6.1 or higher)
• Clone this repository
• Install the com.unity.ml-agents Unity package
• Install the mlagents Python package

Install Unity 2018.4 or Later

Download and install Unity. We strongly recommend that you install Unity through the Unity Hub as it will enable you to manage multiple Unity versions.

Install Python 3.6.1 or Higher

We recommend installing Python 3.6 or 3.7. If your Python environment doesn't include pip3, see these instructions on installing it.

Although we do not provide support for Anaconda installation on Windows, the previous Windows Anaconda Installation (Deprecated) guide is still available.

Clone the ML-Agents Toolkit Repository

Now that you have installed Unity and Python, you will need to clone the ML-Agents Toolkit GitHub repository to install the Unity package (the Python packages can be installed directly from PyPi - a Python package registry).

git clone --branch release_1 https://github.com/Unity-Technologies/ml-agents.git

The --branch release_1 option will switch to the tag of the latest stable release. Omitting that will get the master branch which is potentially unstable.

Install the com.unity.ml-agents Unity package

The Unity ML-Agents C# SDK is a Unity Package. You can install the com.unity.ml-agents package directly from the Package Manager registry without cloning this repository. Please make sure you enable 'Preview Packages' in the 'Advanced' dropdown in order to find it.

If you want to try newer features from our development branch you can still install the local package from the repo that you just cloned.

Add the local com.unity.ml-agents package to your project by:

1. navigating to the menu Window -> Package Manager.
2. In the package manager window click on the + button.
3. Select Add package from disk...
4. Navigate into the com.unity.ml-agents folder.
5. Select the package.json file.

NOTE: In Unity 2018.4 the + button is on the bottom right of the packages list, and in Unity 2019.3 it's on the top left of the packages list.

If you are going to follow the examples from our documentation, you can open the Project folder in Unity and start tinkering immediately.

Install the mlagents Python package

Installing the mlagents Python package involves installing other Python packages that mlagents depends on. So you may run into installation issues if your machine has older versions of any of those dependencies already installed. Consequently, our supported path for installing mlagents is to leverage Python Virtual Environments. Virtual Environments provide a mechanim for isolating the dependencies for each project and are supported on Mac / Windows / Linux. We offer a dedicated guide on Virtual Environments.

To install the mlagents Python package, activate your virtual environment and run from the command line:

pip3 install mlagents

Note that this will install mlagents from PyPi, not from the cloned repo. If you installed this correctly, you should be able to run mlagents-learn --help, after which you will see the Unity logo and the command line parameters you can use with mlagents-learn.

By installing the mlagents package, the dependencies listed in the setup.py file are also installed. These include TensorFlow (Requires a CPU w/ AVX support).

Advanced: Installing for Development

If you intend to make modifications to mlagents or mlagents_envs, you should install the packages from the cloned repo rather than from PyPi. To do this, you will need to install mlagents and mlagents_envs separately. From the repo's root directory, run:

pip3 install -e ./ml-agents-envs
pip3 install -e ./ml-agents

Running pip with the -e flag will let you make changes to the Python files directly and have those reflected when you run mlagents-learn. It is important to install these packages in this order as the mlagents package depends on mlagents_envs, and installing it in the other order will download mlagents_envs from PyPi.

Next Steps

The Getting Started guide contains several short tutorials on setting up the ML-Agents Toolkit within Unity, running a pre-trained model, in addition to building and training environments.

Help

If you run into any problems regarding ML-Agents, refer to our FAQ and our Limitations pages. If you can't find anything please submit an issue and make sure to cite relevant information on OS, Python version, and exact error message (whenever possible).