farama-foundation/gymnasium

★ 11,880PythonAudience · researcherComplexity · 3/5Setup · easy

Mindmap

mindmap
  root((Gymnasium))
    What it does
      RL environment API
      Algorithm testing
      Benchmark suite
    Environment families
      Classic Control
      Atari games
      MuJoCo robotics
      Toy Text
    Usage
      reset and step API
      Reward signals
      Episode tracking
    Ecosystem
      PettingZoo multi-agent
      Community envs
      Stable Baselines

mindmap root((Gymnasium)) What it does RL environment API Algorithm testing Benchmark suite Environment families Classic Control Atari games MuJoCo robotics Toy Text Usage reset and step API Reward signals Episode tracking Ecosystem PettingZoo multi-agent Community envs Stable Baselines

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Test and compare reinforcement learning algorithms against classic control problems like CartPole or MountainCar without writing your own simulation.

USE CASE 2

Train an AI agent to play Atari video games using the built-in Atari environment family as a benchmark.

USE CASE 3

Use Gymnasium as the environment interface when building a custom simulation so it is compatible with any existing RL library like Stable Baselines or RLlib.

USE CASE 4

Run a quick sanity check that a new learning algorithm works at all using the deliberately tiny Toy Text environments before scaling up.

Tech stack

PythonMuJoCoBox2D

Getting it running

Difficulty · easy Time to first run · 5min

Heavy environment families like MuJoCo or Atari require additional dependencies installed separately via pip extras.

In plain English

Gymnasium is an open-source Python library that gives researchers and developers a standard way to build and test reinforcement learning experiments. Reinforcement learning is a branch of AI where a software agent learns to make decisions by interacting with an environment and receiving feedback on whether its actions were good or bad. Gymnasium provides the shared language that lets a learning algorithm talk to any compatible environment without needing custom glue code for each combination. The project started as a fork of OpenAI's Gym library, which OpenAI handed off to an outside team. That outside team, the Farama Foundation, now maintains it here as Gymnasium, where all future development happens. Out of the box, Gymnasium ships several families of test environments. Classic Control covers physics problems like balancing a pole on a cart. Box2D includes toy games built around 2D physics. Toy Text environments are deliberately tiny and simple, useful for checking that a learning algorithm works at all before scaling up. MuJoCo environments simulate complex multi-joint bodies, like robotic limbs, and are more demanding. Atari environments replay hundreds of classic video games so agents can try to learn to play them. A growing collection of third-party environments built by the broader community also works with the same API. The programming interface is straightforward. You pick an environment by name, call a reset to start a new session, and then repeatedly call step to send an action and get back what the agent observes next, a reward signal, and a flag indicating whether the episode ended. A short code sample in the README shows this loop running in about ten lines of Python. Installation is done through pip. The base package is small, optional extras install the heavier dependencies for specific environment families like Atari or MuJoCo, or you can install everything at once. Python 3.10 through 3.13 on Linux and macOS are officially supported. Gymnasium is widely used in academic research and as a starting point for anyone learning about reinforcement learning. Related libraries from the same foundation, such as PettingZoo for multi-agent setups, extend the same API conventions into other scenarios.

Copy-paste prompts

Prompt 1

I'm using Gymnasium to train a reinforcement learning agent on CartPole-v1. Show me the full training loop using a simple Q-learning algorithm: reset, step, compute reward, update Q-table, and track episode length over 1000 episodes.

Prompt 2

Using Gymnasium's Atari environment, help me set up the Breakout-v5 env with frame stacking and grayscale preprocessing, then run 100 random-action steps and print the total reward.

Prompt 3

I want to wrap a Gymnasium environment to normalize observations to the range 0-1 and clip rewards to -1/+1. Show me how to write a custom ObservationWrapper and RewardWrapper and apply both to LunarLander-v2.

Prompt 4

Help me create a custom Gymnasium environment for a simple grid-world where an agent moves on a 5x5 grid, implementing the reset, step, and render methods to meet the Gymnasium API.

Open on GitHub → Explain another repo

← farama-foundation on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.