Gymnasium: the Python RL environment API, and how to install it

What Gymnasium standardises, and who that helps

Reinforcement learning code has two halves: the algorithm and the environment it learns in. Without a shared contract, every algorithm is written against one simulator and every simulator is written for one algorithm. Gymnasium exists to break that coupling. It is, per the README, "a standard API to communicate between learning algorithms and environments, as well as a standard set of environments compliant with that API."

The audience is narrow and specific. Researchers who need to compare two algorithms on the same task without rewriting the task. Library authors who want their trainer to run on any environment a user brings. People learning RL who want a small, deterministic task to debug against, which is exactly what the Toy Text family is for. The project is a fork of OpenAI's Gym by its maintainers, and the README states this is where future maintenance will occur. That matters if you have old Gym code: the API changed between the two, and the fork is the line that continues.

The package is pure Python with four base dependencies (numpy, cloudpickle, typing-extensions, farama-notifications) and requires Python 3.10 or newer. Nothing about the core install pulls in a physics engine or a renderer.

The env contract: reset, step, and the five-tuple

The mechanism is a Python class convention, not a framework. An environment exposes action_space and observation_space, and two methods. reset returns an observation and an info dict. step takes an action and returns five values: observation, reward, terminated, truncated, info.

The split between terminated and truncated is the part worth understanding. Terminated means the task ended on its own terms, for example the pole fell. Truncated means an external limit cut the episode short, typically a time limit. Collapsing both into one boolean, as older Gym did, hides the difference between a policy that failed and a policy that ran out of clock, and that difference changes how you bootstrap value estimates. Gymnasium keeps them separate.

The README's example shows the whole loop with CartPole-v1, including the seed argument to reset and the reset-on-done pattern. Note that reset takes seed as a keyword and returns a tuple, not a bare observation. Code written for Gym before this change will break on both counts.

Environment naming carries a version suffix. The README is explicit: all environments end in a suffix like "-v0", and when a change might affect learning results the number is increased. That is a reproducibility guarantee, not decoration. If a benchmark reports CartPole-v1 results, the version pins what those results mean.

Installing Gymnasium and running CartPole-v1

The base library installs from PyPI with no extras. The README gives the command directly, and it is the same on Linux, macOS and Windows because the core has no compiled dependencies.

pip install gymnasium

After that, a first run needs no environment family at all, because CartPole-v1 is part of the core package. The README's example is the shortest real use: make the environment, seed it for reproducibility, sample random actions, and reset when the episode ends.

import gymnasium as gym
env = gym.make("CartPole-v1")

observation, info = env.reset(seed=42)
for _ in range(1000):
    action = env.action_space.sample()
    observation, reward, terminated, truncated, info = env.step(action)

    if terminated or truncated:
        observation, info = env.reset()
env.close()

This is a random policy, so expect the pole to fall quickly and the loop to reset several times inside 1000 steps. The import name is gymnasium even though the pip package is also gymnasium; there is no separate module name to remember.

If you want anything beyond Classic Control, Toy Text and the core utilities, install an extra. The README names the pattern and the pyproject file lists the groups: atari, box2d, classic-control, mujoco, toy-text, jax and torch.

pip install "gymnasium[atari]"
pip install "gymnasium[all]"

The README warns that installing everything is heavy and that some dependencies are problematic on certain systems, which is why the per-family extras exist. The box2d extra is the clearest example: pyproject resolves box2d ==2.3.10 on Python below 3.14, and on 3.14 and above switches to box2d-py ==2.3.8 with swig, because the box2d wheel stops at 3.13 and there is no source distribution. If you are on 3.14 and Box2D fails, that conditional is the first place to look.

Where Gymnasium is the wrong tool

The API models single-agent environments. The README says so plainly, and it points to PettingZoo as the multi-agent counterpart. If your problem is two agents negotiating, or a population competing, forcing it into one env class means encoding the other agents into the observation and the action space, which loses the semantics you probably care about.

Gymnasium is also not a training library. It will not give you a PPO implementation, a replay buffer or a logger. The README's related-libraries list points newcomers to CleanRL for reference implementations, which is an admission that the algorithm side lives elsewhere. If you want one package that does both, Gymnasium alone will disappoint you.

The third constraint is versioning. The strict -vN suffix means an environment can change behaviour between versions, and the version bump is the signal. That is good for reproducibility and mildly annoying for anyone who pinned CartPole-v0 and then found CartPole-v1. Treat environment IDs as part of your experiment configuration, not as constants.

Finally, third-party environments are a compatibility risk. The README advises checking which version the software was built for and using apply_env_compatibility in gymnasium.make if necessary. That function exists because the ecosystem did not migrate in lockstep. Expect to need it.

Gymnasium against PettingZoo and CleanRL

The honest comparison is not Gymnasium versus some rival single-agent API, because there is not one worth naming here. It is Gymnasium versus the two projects the README itself recommends, and they differ in what layer they occupy.

PettingZoo is the multi-agent version, maintained by the same foundation. Where Gymnasium gives you one env with one action space, PettingZoo gives you a set of agents each with their own spaces and a turn-taking or simultaneous step model. Same family, different contract. Choosing between them is a question about your problem, not about quality.

CleanRL sits above the API. It is, per the README, a learning library designed for newcomers with reference implementations. CleanRL consumes Gymnasium environments; it does not replace them. If you want to read a PPO implementation end to end, that is CleanRL's job. If you want your own implementation to run against CartPole and Atari without two code paths, that is Gymnasium's job.

The Farama Foundation also maintains a collection of other environments that use the Gymnasium API, so the ecosystem argument runs through this interface. That is the real reason to adopt it: not that it is the best environment, but that it is the one other people write against.

Maintenance, licensing and upgrade cost

The repository is not archived and the last push was on 2026-09-21, the same day as this writing, so it is under current development. Recent releases run v1.2.2 in November 2025, v1.2.3 in December 2025 and v1.3.0 in April 2026. The cadence is steady rather than frantic, which fits a project whose main asset is a stable interface.

The licence is MIT, stated in pyproject as "MIT License" and in the repository LICENSE file. MIT is permissive: you can use, modify and redistribute it, including in closed products, provided the copyright notice and permission notice are preserved. That is a summary of the licence text, not legal advice; read LICENSE yourself if the distinction matters to your organisation.

Upgrade cost is mostly on the environment side. Because the version suffix changes when learning results might change, a minor release can shift numbers on an existing benchmark. The mitigation is to pin both the gymnasium version and the environment IDs in your experiment config, then re-run when you deliberately upgrade. The other cost is the Gym to Gymnasium migration: reset and step return different shapes, and there is no compatibility shim mentioned in the README for the old signatures.

What to check before you commit

Confirm Python 3.10 or newer, since pyproject sets requires-python to ">= 3.10" and the classifiers list 3.10 through 3.14. Confirm the extra you need resolves on your platform, especially box2d on Python 3.14 where the dependency switches to box2d-py with swig. If you are migrating an existing Gym codebase, count how many places call env.reset() and unpack a single observation, because every one of them needs the tuple form.

If you depend on a third-party environment, check the version it was built for before wiring it in, and keep apply_env_compatibility in mind as the escape hatch the README names. And if your task involves more than one learning agent, stop here and look at PettingZoo instead; that is not a limitation you can work around cleanly inside a single-agent API.

Editorial conclusion

Adopt Gymnasium if you write or compare RL algorithms and want a stable env contract, versioned environments and reference tasks you do not have to build. Do not adopt it if you need multi-agent semantics, which is PettingZoo's job, or if you want a training library rather than an interface. Before committing, check that your Python is 3.10 or newer, that the extra you need installs on your platform (the box2d extra has no source distribution and switches to box2d-py plus swig on Python 3.14), and whether your existing code calls the old gym API, in which case plan the migration rather than assuming a drop-in import swap.

Frequently asked questions

Official sources

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