Update installation doc #6242
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,7 +38,7 @@ The table below shows our latest release, including our `develop` branch which i | |
|
|
||
| | **Version** | **Release Date** | **Source** | **Documentation** | **Download** | **Python Package** | **Unity Package** | | ||
| |:----------------------:|:-------------------:|:-----------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------:|:-----------------------------------------------------:|:-------------------------------------------------------------------------------------:| | ||
| | **Release 23** | **August 28, 2025** | **[source](https://github.com/Unity-Technologies/ml-agents/tree/release_23)** | **[docs](https://docs.unity3d.com/Packages/[email protected]/manual/index.html)** | **[download](https://github.com/Unity-Technologies/ml-agents/archive/release_23.zip)** | **[1.1.0](https://pypi.org/project/mlagents/1.1.0/)** | **4.0.0** | | ||
| | **develop (unstable)** | -- | [source](https://github.com/Unity-Technologies/ml-agents/tree/develop) | [docs](https://github.com/Unity-Technologies/ml-agents/tree/develop/com.unity.ml-agents/Documentation~/index.md) | [download](https://github.com/Unity-Technologies/ml-agents/archive/develop.zip) | -- | -- | | ||
|
|
||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -2,73 +2,50 @@ | |||||||||||||||||||||||||||||||||
| To install and use the ML-Agents Toolkit, follow the steps below. Detailed instructions for each step are provided later on this page. | ||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| 1. Install Unity (6000.0 or later) | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
| 2. Install Python using conda (>= 3.10.1, <=3.10.12) - we recommend using 3.10.12 | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
| 3. Install ML-Agents using one of the following methods: | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| 3.1 Package installation | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
| 3.2 Advanced installation | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| ## 1. Install **Unity 6000.0** or Later | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| [Download](https://unity3d.com/get-unity/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. | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| ## 2. Install **Python 3.10.12** using Conda | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| We recommend using [conda](https://docs.conda.io/en/latest/) or [mamba](https://github.com/mamba-org/mamba) to install and manage Python environments. | ||||||||||||||||||||||||||||||||||
maryamziaa marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||
| Once conda has been installed on your system, open a terminal and execute the following commands to set up a Python 3.10.12 virtual environment and activate it: | ||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||
| Once conda has been installed on your system, open a terminal and execute the following commands to set up a Python 3.10.12 virtual environment and activate it: | |
| To install Python, follow these steps: | |
| 1. Install [Conda](https://docs.conda.io/en/latest/) or [Mamba](https://github.com/mamba-org/mamba). | |
| 2. Open a terminal and create a new Conda environment with Python 3.10.12: | |
| ```shell | |
| conda create -n mlagents python=3.10.12 && conda activate mlagents |
-
On Windows, install PyTorch separately to ensure CUDA support:
pip3 install torch~=2.2.1 --index-url https://download.pytorch.org/whl/cu121
If prompted, install Microsoft Visual C++ Redistributable. For more installation options and versions, refer to the PyTorch installation guide.
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ```shell |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| conda create -n mlagents python=3.10.12 && conda activate mlagents |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ``` |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| On Windows, you'll have to install the PyTorch package separately prior to installing ML-Agents in order to make sure the cuda-enabled version is used, rather than the CPU-only version. Activate your virtual environment and run from the command line: |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ```sh |
Collaborator
There was a problem hiding this comment.
Suggested change
| pip3 install torch~=2.2.1 --index-url https://download.pytorch.org/whl/cu121 |
Collaborator
There was a problem hiding this comment.
Suggested change
| ``` |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| Note that on Windows, you may also need Microsoft's Visual C++ Redistributable if you don't have it already. See the [PyTorch installation guide](https://pytorch.org/get-started/locally/) for more installation options and versions. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ## 3.1 Install ML-Agents - Package Installation | |
| ## Install ML-Agents |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| Use this installation method if you do not plan to modify or extend the ML-Agents Toolkit for your purposes and you don't need access to our example environments. | |
| You can install ML-Agents in two ways: | |
| * Package installation: Recommended for most users who want to use ML-Agents without modifying the source code. | |
| * Advanced installation: For contributors, developers extending ML-Agents, or users who want access to the example environments. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ### 3.1.1 Install the `com.unity.ml-agents` Unity package | |
| ### Install ML-Agents (Package installation) | |
| Use this method if you don’t plan to modify the toolkit or need the example environments. | |
| #### Install the Unity package | |
| To install the package, follow these steps: | |
| 1. In Unity, open **Window** > **Package Manager**. | |
| 2. Select **+** > **Add package by name**. | |
| 3. Enter `com.unity.ml-agents`. | |
| 4. Enable **Preview Packages** under the **Advanced** drop-down list if the package doesn’t appear. | |
| If the package isn’t listed, follow the [Advanced Installation](#32-install-ml-agents---advanced-installation) method instead. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| 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](https://docs.unity3d.com/Manual/upm-ui-install.html). Please make sure you enable 'Preview Packages' in the 'Advanced' dropdown in order to find the latest Preview release of the package. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| **NOTE:** If you do not see the ML-Agents package listed in the Package Manager please follow the [Advanced Installation](#32-install-ml-agents---advanced-installation) instructions at the bottom of this page. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ### 3.1.2 Install Python package | |
| ### Install the Python package |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| 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 mechanism for isolating the dependencies for each project and are supported on Mac / Windows / Linux. We offer a dedicated [guide on Virtual Environments](Using-Virtual-Environment.md). | |
| Install the ML-Agents Python package to enable communication between Unity and your machine learning training environment. | |
| Using a Python virtual environment helps isolate project dependencies and prevent version conflicts across your system. Virtual environments are supported on macOS, Windows, and Linux. For more information, refer to [Using Virtual Environments](https://github.com/Unity-Technologies/ml-agents/pull/6242/files/Using-Virtual-Environment.md). | |
| 1. Before installing ML-Agents, activate the Conda environment you created: | |
conda activate mlagents
2. Install the ML-Agents Python package from the Python Package Index (PyPI):
python -m pip install mlagents==1.1.0
Make sure to install a Python package version that matches your Unity ML-Agents package version. For information on compatible versions, refer to the [ML-Agents release history](https://github.com/Unity-Technologies/ml-agents/releases).
3. If you encounter an error while building the `grpcio` wheel, install it separately before reinstalling ML-Agents:
conda install "grpcio=1.48.2" -c conda-forge
This step resolves dependency conflicts that can occur with older versions of `grpcio`.
4. When the installation completes successfully, all the required Python dependencies listed in the [setup.py file](https://github.com/Unity-Technologies/ml-agents/blob/release/4.0.0/ml-agents/setup.py), including [PyTorch](Background-PyTorch.md) are automatically configured.
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| You can install the ML-Agents Python package directly from PyPi. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| **Important:** Ensure you install a Python package version that matches your Unity package version. Check the [release history](https://github.com/Unity-Technologies/ml-agents/releases) to find compatible versions. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| When you install the Python package, the dependencies listed in the [setup.py file](https://github.com/Unity-Technologies/ml-agents/blob/release/4.0.0/ml-agents/setup.py) are also installed. These include [PyTorch](Background-PyTorch.md). |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ## 3.2 Install ML-Agents - Advanced Installation | |
| ### Install ML-Agents (Advanced Installation) | |
| Use the advanced installation method if you plan to modify or extend the ML-Agents Toolkit, or if you want to download and use the example environments included in the repository. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| You will need to clone the repository if you plan to modify or extend the ML-Agents Toolkit for your purposes, or if you'd like to download our example environments. Some of our tutorials / guides assume you have access to our example environments. | |
| #### Clone the ML-Agents repository | |
| Clone the ML-Agents repository to access the source code, sample environments, and development branches. | |
| To clone the latest stable release, run: | |
git clone --branch release_23 https://github.com/Unity-Technologies/ml-agents.git
The `--branch release_23` flag checks out the latest stable release. If you omit this option, the `develop` branch is cloned instead, which may contain experimental or unstable changes.
If the `release` branch does not work as expected, switch to the `develop` branch. It may include fixes for dependency or compatibility issues.
To clone the bleeding-edge development version (optional), run:
git clone https://github.com/Unity-Technologies/ml-agents.git
If you plan to contribute your changes, clone the `develop` branch (omit the `--branch` flag). For more information, refer to the [Contribution Guidelines](https://github.com/Unity-Technologies/ml-agents/pull/6242/files/CONTRIBUTING.md).
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| The `--branch release_23` option will switch to the tag of the latest stable release. Omitting that will get the `develop` branch which is potentially unstable. However, if you find that a release branch does not work, the recommendation is to use the `develop` branch as it may have potential fixes for bugs and dependency issues. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| To get the bleeding-edge development version (optional): |
Collaborator
There was a problem hiding this comment.
Suggested change
| ```sh |
Collaborator
There was a problem hiding this comment.
Suggested change
| git clone https://github.com/Unity-Technologies/ml-agents.git |
Collaborator
There was a problem hiding this comment.
Suggested change
| ``` |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| If you plan to contribute those changes back, make sure to clone the `develop` branch (by omitting `--branch release_23` from the command above). See our [Contributions Guidelines](CONTRIBUTING.md) for more information on contributing to the ML-Agents Toolkit. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ### 3.2.1 Add the `com.unity.ml-agents` Unity package | |
| #### Add the ML-Agents Unity package | |
| After cloning the repository, add the `com.unity.ml-agents` Unity package to your project. | |
| To add the local package, follow these steps: | |
| 1. In the Unity Editor, go to **Window** > **Package Manager**. | |
| 2. In the **Package Manager** window, select **+**. | |
| 3. Select **Add package from disk**. | |
| 4. Navigate to the cloned repository and open the `com.unity.ml-agents` folder. | |
| 5. Select the `package.json` file. | |
| Unity adds the ML-Agents package to your project. | |
| If you plan to use the example environments provided in the repository, open the **Project** folder in Unity to explore and experiment with them. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| You can [add the local](https://docs.unity3d.com/Manual/upm-ui-local.html) `com.unity.ml-agents` package (from the repository that you just cloned) to your project by: |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. Navigating to the menu `Window` -> `Package Manager`. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| 2. In the package manager window, click on the `+` button on the top left of the packages list. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| 3. Select `Add package from disk...` |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| 4. Navigate into the `com.unity.ml-agents` folder. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 5. Select the `package.json` file. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| If you are going to follow the examples from our documentation, you can open the `Project` folder in Unity and start tinkering immediately. |
Outdated
Collaborator
There was a problem hiding this comment.
Suggested change
| ### 3.2.2 Install Python package | |
| #### Install the ML-Agents Python package | |
| Install the Python packages from the cloned repository to enable training and environment communication. | |
| 1. From the root of the cloned repository, activate your virtual environment and run: | |
cd /path/to/ml-agents
python -m pip install ./ml-agents-envs
python -m pip install ./ml-agents
This installs the ML-Agents packages directly from the cloned source, not from PyPI.
2. To confirm a successful installation, run:
mlagents-learn --help
If the command lists available parameters, your setup is complete.
3. If you plan to modify the ML-Agents source code or contribute changes, install the packages in editable mode.
Editable installs let you make live changes to the Python files and test them immediately.
From the repository’s root directory, run:
pip3 install torch -f https://download.pytorch.org/whl/torch_stable.html
pip3 install -e ./ml-agents-envs
pip3 install -e ./ml-agents
> [!NOTE]
> Install the packages in this order. The `mlagents` package depends on `mlagents_envs`. Installing them in the reverse order causes `mlagents_envs` to be downloaded from PyPI, which can cause version mismatches.
Outdated
Collaborator
There was a problem hiding this comment.
You may please delete all the following information as it has been covered in the steps above.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.