MAgent2 builds gridworlds with far too many agents in them

Many pixel agents, one gridworld, competitive scenarios

The description is a library for the creation of environments where large numbers of pixel agents in a gridworld interact in battles or other competitive scenarios, and the project summary calls it an engine for high performance multi-agent environments with very large numbers of agents, along with a set of reference environments. The scale is the point. Most multi-agent reinforcement learning work is done with tens of agents, and the environments that exist for those cases are well served by what is already there. A study that wants hundreds or thousands of agents in one simulation needs a different kind of engine, one where the agents are not expensive objects with a Python object each, and that is the problem MAgent2 addresses. The reference environments implement scenarios you would recognise from the literature, adversarial pursuit among others, and they are the reason to look at the project even if your own scenario is different.

The fork, and the environments that moved out of PettingZoo

The history is explained in the readme and it is not just a rename. MAgent2 is a maintained fork of the original MAgent codebase, and it contains a set of reference environments implemented using the PettingZoo API. Those environments used to be included in PettingZoo itself, and they were moved out to exist independently here, with the reason stated plainly, that they are being regularly maintained and will receive bug fixes and support for new versions of Python. The naming history is explained too, because development used to take place at Farama-Foundation/MAgent and was moved to Farama-Foundation/MAgent2 so that the distinction from the original MAgent library is clear to users. So there are two things to keep apart when you read about this area, the original MAgent research platform from 2018 and the modern Farama-maintained engine, and the reference environments that now live with the latter. The citations section in the readme handles this too, giving the original conference paper and a separate citation for the repository with its modifications.

The build is CMake wearing a setuptools costume

The most interesting thing in the repository is the packaging, because the simulation core is not pure Python. The `setup.py` defines a `CMakeExtension` and a custom `build_ext` command, and the first thing that command does is check that CMake is present:

cmake .
make -j threads
move libmagent -> build/

Those three lines are the build process as the script documents it, and if CMake is missing the build stops with an error saying CMake must be installed to build the extensions, listing the names of the extensions that will be affected. The script then works out where the extension should land using the path setuptools computed for it, and passes CMake a build type, either Debug or Release, along with the library, runtime and archive output directories so the artefacts land where setuptools expects them. The version is not in the manifest either, it is read out of the `__version__` line in `magent2/__init__.py`, which is a pattern that keeps the package version and the source of truth in one place.

The Python side is small, and it is built on PettingZoo

The dependency list in the project metadata is three packages long, and they are the whole story. NumPy at 1.21 or newer for the array work, `pygame-ce` at 2.1.0 or newer for the rendering of the gridworld, and PettingZoo at 1.23.1 or newer for the multi-agent API. That last one is the strategically important dependency, because PettingZoo is the interface the reference environments are written against and the interface your own environments would be written against, which means the standard multi-agent tooling applies to an MAgent2 environment. The classifiers also describe the intended audience as science and research, the topic as artificial intelligence, and the development status as production stable. The formatting and import rules are configured in the same file, with isort on the black profile, an indent of four, and the source paths covering both the `magent2` package and the documentation scripts.

The Python floor is stated twice, and the two statements disagree

A small inconsistency in the documentation is worth a paragraph, because it is the kind of thing that costs somebody an afternoon. The requirements section of the readme says MAgent2 supports Linux and macOS and Python 3.8 and later. The project metadata says something different. It sets `requires-python` to 3.11 or newer and lists classifiers for Python 3.11, 3.12, 3.13 and 3.14, so the package you actually install from PyPI will refuse to install on 3.8, 3.9 or 3.10 even though the readme says 3.8 is supported. The classifiers also list Windows as a supported operating system, while the readme's requirements line names only Linux and macOS. Neither statement is fatal on its own, but a reader who trusts the readme and tries Python 3.9 will find the install fails, and the release history explains why, since the 0.3.3 release in 2024 was about Python 3.11 support and installation fixes.

Releases that exist to keep up with Python

The release list is short and each entry describes the point of it. Version 0.3.2 was published in January 2023, 0.3.3 in August 2024 and is described as Python 3.11 support and installation fixes, and 0.3.4 in May 2026 is described as Python 3.14 support. That is a project whose releases are, in effect, a compatibility ledger, which matches the readme's own claim that the environments are regularly maintained and will receive bug fixes and support for new versions of Python. The last push to the repository was on 2026-10-17, so the tree is well ahead of the last tagged release. The governance is Farama Foundation, with a named project manager, Travis Virgil, and the wider Farama team contributing maintenance. The repository carries a code of conduct, a pre-commit configuration, a Justfile, a `mise.toml` for tool versions and a `CMakeLists.txt` at the root, which is the shape of a project that expects a specific development environment.

Who it is for, and what it is not

It helps to say plainly what MAgent2 is and is not. It is not a reinforcement learning algorithm, and it is not a training framework, it is the environment layer, the part that decides where the agents are, what they can see and what happens when they collide. It is not a general purpose simulator either, the reference scenarios are competitive and grid based, and the design assumes that many agents move independently in a shared space. The engine is the part that scales, and the environments are the part that tells you whether the scaling is useful, which is why the fork moved the environments out of PettingZoo rather than leaving them there, since a reference environment that nobody maintains is worse than no reference environment at all. So the sensible way to evaluate it is to run one of the reference scenarios at a scale that makes your own scenario plausible, which is a measure of the engine and a template for your work at the same time.

Editorial conclusion

MAgent2 suits a reinforcement learning researcher who needs many agents interacting, since the reference environments are the ones that were the reason to build the engine, and it suits a team that wants its environments to follow the PettingZoo API so that the standard multi-agent tooling applies. It is a poor fit if you need a pure Python install on Windows, since the build needs CMake and the documentation says the project supports Linux and macOS. Before you adopt it, check three things: which Python you have, since the readme says 3.8 and later while the package metadata requires 3.11, that you can install CMake, because the setup script refuses to build without it, and whether you need the reference environments or only the engine, since the environments were the reason for the fork and the engine is the part that scales.

Frequently asked questions

Official sources

1. Farama-Foundation/MAgent2 on GitHub
2. License: MIT
3. Project website
4. README
5. Releases