# 2. Installing ML-Agents and Python
Part of [[ML-Agents and Inference Engine]]. Prev: [[1. ML-Agents Sentis and the Training Loop]]. Next: [[3. Platformer Agent Observations Actions Rewards]].
All versions below are from the official pages fetched 2026-11-13. Re-check the 4.2 install page before a semester; the Python pins are the part most likely to change.
## 2.1 Unity side
1. Unity **6000.5+** project (URP 3D template is fine). ML-Agents 4.x needs Unity **6000.0 or later**.
2. **Window > Package Manager > + > Add package by name** > `com.unity.ml-agents`. The 6000.5 page shows **4.1.0** as the released version for that Editor and **4.2.0** also available. Prefer what Package Manager resolves; if you add `4.2.0` explicitly, note it in your README so students match.
3. ML-Agents pulls in **Sentis** (`com.unity.ai.inference`) as a dependency (4.0.3+ upgraded to Sentis 2.6.1; the 6000.5 Sentis page shows **2.6.1** released). You do not install it separately for ML-Agents. For part 6 (Sentis directly) it is the same package.
4. Make sure the **Input System** is installed and Active Input Handling allows it (the heuristic in part 3 uses `Keyboard.current`). See [[Input System]].
> [!note] Example environments
> The package install does **not** include the sample environments (3DBall, Walker, etc.). For those, clone the repo at `release/4.2.0` and open its `Project` folder (the 4.2 install page's Advanced Installation). Do that once on your own machine to see what "trained" looks like before teaching it.
## 2.2 Python side (Windows)
The 4.2 install page uses **Conda** (or Mamba) for an isolated environment.
```shell
:: 1. Create and activate the environment (Python 3.10.12, per the 4.2 install page)
conda create -n mlagents python=3.10.12 && conda activate mlagents
:: 2. Install PyTorch FIRST, pinned to the supported range, from the CUDA 12.1 index on Windows
pip3 install "torch>=2.1.1,<=2.8.0" --index-url https://download.pytorch.org/whl/cu121
:: 3. Install the trainer
python -m pip install mlagents==1.1.0
:: 4. Check
mlagents-learn --help
```
Why the order matters (from the install page): `mlagents` 1.1.0 does not cap the PyTorch version, so if you skip step 2, pip may install a newer PyTorch, and "PyTorch 2.9 and later include ONNX changes that break ML-Agents model export". If the `grpcio` wheel fails to build, the page suggests `conda install "grpcio=1.48.2" -c conda-forge` and then reinstalling `mlagents`.
No NVIDIA GPU? PPO on small vector observations trains fine on CPU; install the CPU build of PyTorch within the same version range (see the PyTorch site) instead of the `cu121` index.
### Compatibility table (4.2 install page)
| Unity `com.unity.ml-agents` | Python `mlagents` / `mlagents-envs` | Python | PyTorch |
|---|---|---|---|
| 4.0.x, 4.1.x, 4.2.x | 1.1.0 (PyPI) | 3.10.1-3.10.12 | 2.1.1-2.8.0 |
PyPI 1.1.0 "predates the Unity package 4.x releases": it works with them but lacks Python-side 4.x changes (the PyTorch 2.8 limit, CUDA/CPU fixes, gym -> gymnasium). For those, use the advanced install:
```shell
git clone --branch release/4.2.0 https://github.com/Unity-Technologies/ml-agents.git
cd ml-agents
pip3 install "torch>=2.1.1,<=2.8.0"
pip3 install -e ./ml-agents-envs
pip3 install -e ./ml-agents
```
Install `ml-agents-envs` before `ml-agents`; the other order pulls `mlagents_envs` from PyPI instead of your clone (install page note). On Windows use the `cu121` index for torch as in 2.2.
## 2.3 Smoke test: Editor <-> trainer
1. In a terminal with the env active, from a folder where you want `results/` to appear:
```shell
mlagents-learn --run-id=SmokeTest
```
2. When it prints that it is waiting for the Editor, press **Play** in a scene that has at least one Agent with **Behavior Type = Default** (part 3's agent, or a sample).
3. The terminal should show the behavior name connecting and step counters rising. Stop with Ctrl+C; it exports an `.onnx` into `results/SmokeTest/`.
## 2.4 Classroom setup tips
- Put the exact commands above in the project README and a `requirements.txt` that pins `torch` and `mlagents`.
- Use one Conda env per course, not per project.
- Lab PCs without admin rights: Miniconda installs per-user.
- Keep training **out of the Unity project folder** (`results/` can grow large) and out of Git ([[Version Control]]).
## Sources
- https://docs.unity3d.com/Packages/
[email protected]/manual/Installation.html
- https://docs.unity3d.com/6000.5/Documentation/Manual/com.unity.ml-agents.html
- https://docs.unity3d.com/6000.5/Documentation/Manual/com.unity.ai.inference.html
- PyTorch install selector: https://pytorch.org/get-started/locally/