Mava: single file JAX implementations for multi-agent reinforcement learning

A research codebase, not a package you depend on

The first instruction in the README is a warning of sorts. At the moment Mava is not meant to be installed as a library, but rather to be used as a research tool, and the recommended path is to clone the repository and install dependencies with uv. That single sentence changes how you should read everything else. Mava is not competing with packaged MARL libraries that you add to requirements.txt and forget. It is a codebase you fork, edit and run from the checkout, built for what the README calls rapid research iteration, hack, modify, and test new ideas fast. The package metadata still exists: pyproject.toml names the distribution id-mava with a dynamic version and packages found under the mava prefix, and the setuptools build backend is configured. But the intended workflow is a working tree with the algorithm files open next to your editor. The people it is for are researchers who need to change an algorithm today and see the effect tonight.

Anakin and Sebulba: the same algorithm, two ways to scale it

The architectural split is the most interesting thing about Mava. It supports two distribution architectures for reinforcement learning systems. The first is Anakin, used when environments are written in JAX, which enables end-to-end JIT compilation of the full MARL training loop so the whole loop runs on hardware accelerators. The second is Sebulba, used when environments are not written in JAX, and the README describes it as particularly useful when a hardware accelerator has to interact with many CPU cores at a time. The choice is therefore forced by your environment, not by taste. The algorithm table in the README shows the same split in practice: ff_ippo is marked for both Anakin and Sebulba, while rec_ippo, rec_mappo and the Q learning variant rec_iql are marked for Anakin only. Which learning paradigm you use, independent learners, centralised training with decentralised execution, or heterogeneous agent learning, is a separate axis from the architecture, and implementations are organised along both.

Cloning, syncing and choosing the JAX build for your accelerator

The install path is short and the README is explicit about the two variants for accelerators:

# Clone the repository
git clone https://github.com/instadeepai/Mava.git
cd Mava
# Create a virtual environment and install all dependencies
uv sync
# Activate the virtual environment
source .venv/bin/activate

For a GPU or TPU aware JAX there are two extras:

uv sync --extra cuda12  # GPU aware JAX
uv sync --extra tpu  # TPU aware JAX

The pip route is the editable install with an extra, and the README notes you can leave out the cuda12 extra if you have no GPU or are on a Mac. Python versions matter here: the README says Mava has been tested on Python 3.11 and 3.12, earlier versions may also work, and the Quickstart notebook on Google Colab uses Python 3.10 because Colab defaults to it. pyproject.toml agrees, with requires-python set to >=3.10,<3.13. A Dockerfile exists as well, built on python:3.12-slim with uv, exposing port 6006 for TensorBoard, and a Makefile with build, run and bash targets that pass GPU flags automatically when nvidia-smi is present.

Running a system: one file, Hydra overrides on the command line

Training a first system means running one of the system files, and the README gives the example directly:

python mava/systems/ppo/anakin/ff_ippo.py

Configuration is handled by Hydra, with the defaults living in the mava/configs/ directory. Because Hydra accepts overrides from the terminal, the same file runs against a different environment or scenario without editing code:

python mava/systems/ppo/anakin/ff_ippo.py env=lbf

and a different scenario on the same environment suite:

python mava/systems/ppo/anakin/ff_ippo.py env=rware env/scenario=tiny-4ag

That is the whole learning loop for a first experiment. There is also a Quickstart notebook at examples/Quickstart.ipynb, with an examples/advanced_usage/ directory beside it, which is the faster route if you would rather see a trained system than configure one. The environments named in the README and the dependency list include Level-based Foraging through lbforaging, rware, matrax, jumanji, the JAX-native Brax and MuJoCo MJX suites at mujoco==3.1.3 and mujoco-mjx==3.1.3, plus gigastep and smaclite, the latter two pulled straight from git.

Evaluation logging built for aggregation, not just watching curves

Mava natively supports logging to json files that adhere to the standard suggested by Gorsane et al. (2022), and the README points out that this makes downstream plotting and aggregation easy using the tools in the MARL-eval library, which is installed as id-marl-eval from the InstaDeep fork of marl-eval. The evaluation convention is treated as a first class feature rather than an afterthought, which matters for anyone who has tried to compare runs across papers. TensorBoard logging is available through the tensorboard_logger dependency, and neptune is in the dependency list as well, so experiment tracking is not locked to one vendor. The environment support is deliberately thin and extensible: Mava gives first class support to a few JAX based MARL environment suites through wrappers, and new environments can be added by using existing wrappers as a guide, which is a realistic expectation for a research codebase rather than a plug-in marketplace.

Old pins, git dependencies and a CUDA mismatch worth checking

There are three concrete things to check before you plan on Mava. The first is the age of the pins. pyproject.toml fixes jax==0.5.3, jaxlib==0.5.3, brax==0.10.3, gymnasium==1.0.0, hydra-core==1.3.4, numpy==1.26.4 and scipy==1.12.0, while flax is constrained to a range below 0.10.4. These are deliberate reproductions of a working environment, which is what you want for a paper, and also what you may want to move away from for new work. The second is that three dependencies come from git rather than an index: gigastep from a personal repository, id-marl-eval from the InstaDeep fork of marl-eval, and jaxmarl from a fork on the jax-05 branch, with a comment saying that this only unpins the version of JAX. Reproducing an experiment months later depends on those forks still existing. The third is a genuine inconsistency in the container path: the Dockerfile installs jax[cuda12]==0.4.30 when the USE_CUDA build argument is true, while pyproject.toml pins jax to 0.5.3, so a CUDA container build and a local uv sync do not produce the same JAX version.

Release tags from 2022 against pushes in 2026

The maintenance picture is mixed and worth stating plainly. The repository is not archived, the default branch is develop rather than main, and the last push was on 2026-09-09. But the release tags visible are 0.1.3 from 2022-06-15, 0.1.2 from 2022-03-28 and 0.1.1 from 2022-02-25, so there has been no tagged release in a long time while the tree itself keeps changing. The version in pyproject.toml is dynamic, so the packaged version is derived at build time rather than pinned in the file. That combination means you should treat the develop checkout, not a tag, as the artefact you depend on, and pin your own commit if you need reproducibility. The licence is Apache-2.0, the permissive choice, which is unusually clean for a research codebase and means no copyleft obligation attaches to code you write against it. The project cites its own write-up on arXiv as 2410.01706.

Editorial conclusion

Mava suits a reinforcement learning researcher who wants to read a whole algorithm in one file, run it on a JAX environment and log results in a format the MARL evaluation tooling already understands. Skip it if you need a maintained library you can pin in a product, because the README says it is not meant to be installed as a library, the releases stop at 0.1.3 from 2022 and several dependencies come from git forks rather than a package index. Before adopting, check that jax==0.5.3 and numpy==1.26.4 in pyproject.toml still build on your accelerator, resolve the version conflict between the pinned jax in pyproject.toml and the jax[cuda12]==0.4.30 installed by the Dockerfile, and confirm the three git-sourced dependencies still resolve before you plan a paper deadline around it.

Frequently asked questions

Official sources

1. instadeepai/Mava on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases