Minigrid: grid-world environments for reinforcement learning research

What Minigrid solves for RL researchers

Training a reinforcement learning agent needs an environment that resets, steps, and returns observations in a predictable shape. Writing that scaffolding yourself, for every task variant, is the part of RL work nobody wants to redo. Minigrid supplies a collection of discrete grid-world environments that already follow the Gymnasium standard API, so the same training loop can be pointed at a door-and-key task, a lava crossing, or a maze without rewriting the plumbing. The README describes the environments as lightweight, fast, and easily customizable, and the intended audience is research on reinforcement learning. The library was previously known as gym-minigrid, which matters if you are following older papers or code that still imports it under that name. Two families ship together: the original Minigrid environments, where a triangle-like agent with a discrete action space moves through a 2D map containing walls, lava, and dynamic obstacles, and the BabyAI environments, imported from the BabyAI project, which add synthetic natural-language instructions such as putting a red ball next to a box. The Minigrid family communicates the task through a mission string returned in the observation; goal-oriented and hierarchical missions include picking up boxes, opening doors with keys, and navigating to a goal. Every environment is programmatically tunable in size and complexity, which is what makes curriculum learning practical rather than aspirational.

How the environment, observation and mission string fit together

The mechanism is the Gymnasium contract. An environment exposes reset and step, and Minigrid registers one or more configurations per environment with Gymnasium, so environments are addressed by registered IDs rather than by hand-constructing classes. The agent is a triangle-like figure on a 2D grid with a discrete action space. Observations carry a mission string describing what the agent is supposed to accomplish, which is the hook for language-conditioned work. The BabyAI collection extends this by generating synthetic natural-looking instructions that command the agent to navigate the world, including unlocking doors, and to move objects to specified locations. Because each environment is programmatically tunable in terms of size and complexity, difficulty is a parameter of the task rather than a separate codebase. That is the design decision worth noting: the environments are not fixed benchmarks, they are generators you adjust. The repository layout reflects the same split, with a minigrid package, a tests directory, and a docs directory, and the package metadata declares numpy, gymnasium, and pygame-ce as runtime dependencies. pygame-ce is the rendering path, so headless training runs still carry that dependency even when nothing is drawn.

Installing Minigrid and running a first environment

The README gives a single install command, and the package metadata sets requires-python to >= 3.10, so the interpreter matters before anything else. The README states that Linux and macOS are supported and that Windows PRs are accepted but the platform is not officially supported.

pip install minigrid

After installation, the first real step is to create an environment through Gymnasium. The README does not print a literal environment ID in the text, so check the documentation's environment list for the exact registered name before running anything; the step below uses the reset and step calls the README names as the Gymnasium interface.

import gymnasium as gym
import minigrid

env = gym.make("...")
obs, info = env.reset()

If the ID is registered, reset returns an observation and info; the mission key holds the task description the README refers to. If the ID is wrong, Gymnasium raises an error naming the unknown environment, which is the fastest way to confirm what your installed version registers.

For training rather than a single rollout, the README points to rl-starter-files, a separate repository of examples for training Minigrid environments with RL algorithms. The README states that this code has been tested and is known to work with the environment, and that the default hyper-parameters are known to converge. That is a claim about that repository, not about your setup; treat it as a starting configuration to reproduce rather than a guarantee.

Where Minigrid is the wrong tool

The limitations follow directly from the design. Observations are small 2D grids with a triangle agent, so anything requiring continuous control, high-dimensional perception, or visual realism has to look elsewhere; the README makes no claim in that direction and the package description calls the environments minimalistic. Platform support is the second constraint: the README says Python 3.10+ on Linux and macOS is supported, and that Windows PRs are accepted but not officially supported, so a Windows-based team is on its own. Third, the library is an environment collection, not a training framework. There is no algorithm implementation in the package; the README directs readers to rl-starter-files for that, and the pyproject dependencies are numpy, gymnasium, and pygame-ce, none of which train anything. If you want an end-to-end pipeline out of the box, you are assembling it yourself. Finally, the mission string is part of the observation, which means any agent architecture you use has to consume text or a tokenised form of it; if your pipeline expects a flat vector observation only, you will be writing the encoder. None of these are defects, but each one is a reason to check the fit before porting an existing project.

Minigrid compared with XLand-MiniGrid and Miniworld

The closest conceptual alternative people search for is XLand-MiniGrid, which also builds on grid-world environments in the JAX ecosystem. The difference in approach is the substrate: Minigrid is a Python package following the Gymnasium API with numpy and pygame-ce as dependencies, so it plugs into the standard Gymnasium training loop and any library that speaks that interface. A JAX-native environment stack changes the loop itself, which buys different things and costs different things. If your training code is already Gymnasium-shaped, that is a real migration cost rather than a drop-in swap. The second comparison is Miniworld, which the project's own citation covers alongside Minigrid in the same paper on modular and customizable reinforcement learning environments for goal-oriented tasks. The README describes Minigrid as discrete grid worlds; Miniworld, by name and by the paper's framing, is the 3D counterpart. If your task needs a first-person or 3D view, Minigrid is the wrong half of that pair. For grounded language learning specifically, the BabyAI environments are the relevant subset, and the README asks that publications using them also cite the BabyAI paper in addition to the Minigrid citation.

Maintenance, upgrades and licence position

The repository is not archived, and the last push was on 2026-09-10, which is recent enough that describing it as maintained is fair on the evidence available. Release cadence is uneven: v3.1.0 landed on 2026-05-11, v2.5.0 (also labelled 3.0.0) on 2024-11-17, and v2.4.0 on 2024-01-27. That gap between the 2.4.0 and 2.5.0 releases is worth knowing if you pin versions, because the 3.0.0 label attached to v2.5.0 signals a major-version transition, and major transitions in an environment library usually mean observation or API changes. The README does not document rollback or a compatibility policy, so a version pin is the only reliable protection. On licensing, the situation needs care: the repository metadata reports NOASSERTION, while pyproject.toml declares license = { text = "MIT License" } and lists the classifier License :: OSI Approved :: MIT License. The LICENSE file exists at the top level but its contents are not reproduced here. If the MIT declaration in the package metadata is accurate, MIT is permissive and imposes few obligations beyond attribution, but the mismatch between the repository-level NOASSERTION and the package-level MIT text is exactly the kind of thing to resolve with your own legal review before shipping anything. This is not legal advice.

Editorial conclusion

Adopt Minigrid if you need small, configurable, Gymnasium-compatible grid worlds for RL experiments, curriculum learning, or grounded language tasks through the BabyAI environments. Do not adopt it if you need continuous control, photorealistic observations, or officially supported Windows runs; the README states the project accepts Windows PRs but does not officially support the platform. Before committing, verify that the environment IDs you want are registered with Gymnasium and that your target Python version satisfies requires-python >= 3.10 in pyproject.toml, then confirm a rollout returns the mission string your task depends on.

Frequently asked questions

Official sources

1. Farama-Foundation/Minigrid on GitHub
2. Issues
3. Project website
4. README
5. Releases