gym README

The project's README from github.com/openai/gym. As one markdown file: README.md.

pre-commit Code style: black

Important Notice

The team that has been maintaining Gym since 2021 has moved all future development to Gymnasium, a drop in replacement for Gym (import gymnasium as gym), and Gym will not be receiving any future updates. Please switch over to Gymnasium as soon as you're able to do so. If you'd like to read more about the story behind this switch, please check out this blog post.

Gym

Gym is an open source Python library for developing and comparing reinforcement learning algorithms by providing a standard API to communicate between learning algorithms and environments, as well as a standard set of environments compliant with that API. Since its release, Gym's API has become the field standard for doing this.

Gym documentation website is at https://www.gymlibrary.dev/, and you can propose fixes and changes to it here.

Gym also has a discord server for development purposes that you can join here: https://discord.gg/nHg2JRN489

Installation

To install the base Gym library, use pip install gym.

This does not include dependencies for all families of environments (there's a massive number, and some can be problematic to install on certain systems). You can install these dependencies for one family like pip install gym[atari] or use pip install gym[all] to install all dependencies.

We support Python 3.7, 3.8, 3.9 and 3.10 on Linux and macOS. We will accept PRs related to Windows, but do not officially support it.

API

The Gym API's API models environments as simple Python env classes. Creating environment instances and interacting with them is very simple- here's an example using the "CartPole-v1" environment:

import 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()

Please note that this is an incomplete list, and just includes libraries that the maintainers most commonly point newcommers to when asked for recommendations.

Environment Versioning

Gym keeps strict versioning for reproducibility reasons. All environments end in a suffix like "_v0". When changes are made to environments that might impact learning results, the number is increased by one to prevent potential confusion.

MuJoCo Environments

The latest "_v4" and future versions of the MuJoCo environments will no longer depend on mujoco-py. Instead mujoco will be the required dependency for future gym MuJoCo environment versions. Old gym MuJoCo environment versions that depend on mujoco-py will still be kept but unmaintained. To install the dependencies for the latest gym MuJoCo environments use pip install gym[mujoco]. Dependencies for old MuJoCo environments can still be installed by pip install gym[mujoco_py].

Citation

A whitepaper from when Gym just came out is available https://arxiv.org/pdf/1606.01540, and can be cited with the following bibtex entry:

@misc{1606.01540,
  Author = {Greg Brockman and Vicki Cheung and Ludwig Pettersson and Jonas Schneider and John Schulman and Jie Tang and Wojciech Zaremba},
  Title = {OpenAI Gym},
  Year = {2016},
  Eprint = {arXiv:1606.01540},
}

Release Notes

There used to be release notes for all the new Gym versions here. New release notes are being moved to releases page on GitHub, like most other libraries do. Old notes can be viewed here.

gym (openai/gym)

Searching Database…

37.2K ·GitHub
Gym
archived
What is this?Gym is an open source Python library for developing and comparing reinforcement learning algorithms. It provides a standard API for learning algorithms to talk to environments, plus a standard set of environments built on that API.
Is this a library I use in my own code, or a standalone program?It is a Python library you import into your own training code, not a standalone app. Environments are modeled as simple Python classes — you create an environment instance like 'CartPole-v1' and interact with it.
Which Python versions and operating systems does it support?Python 3.7, 3.8, 3.9 and 3.10 on Linux and macOS. PRs for Windows are accepted, but Windows is not officially supported.
Is Gym still actively maintained?No — the repository is archived. The maintaining team moved all future development to Gymnasium, a drop-in replacement (import gymnasium as gym), and Gym will receive no updates, so new projects should start with Gymnasium.
What does working with an environment look like?You instantiate an environment as a Python class instance, like 'CartPole-v1', and interact with it through the standard API. Environments carry strict version suffixes so experiments stay reproducible.
Which RL libraries can I pair it with?CleanRL for beginner-friendly reference implementations, Tianshou for experienced users who tweak algorithms, RLlib for distributed training and inference, and PettingZoo for multi-agent environments.
Why do environment names end in versions like 'v0'?Strict versioning for reproducibility: whenever a change to an environment could impact learning results, the version number is bumped so results are not silently compared across different environment behavior.
What changed with the MuJoCo environments?From v4 on they depend on mujoco instead of mujoco-py; install with pip install gym[mujoco]. Old mujoco-py-based versions remain available via gym[mujocopy] but are unmaintained.
What are similar projects?dopamine, Gymnasium, AirSim, hypoarena, FluxVLA, lerobot, sktime, dqn-adaptive-cpu-scheduler
Which topics is it in?simulation, algorithms, reinforcement-learning, deprecated, benchmark, openai, framework, research, machine-learning, api, library, ai
Creator
openai
Size
7 MB
Stars
37.2K
Updated
CommitMar 26Release0.26.2Oct 04
Age
10y
Commits · 90 Days