Register and Make#

Gymnasium allows users to automatically load environments, pre-wrapped with several important wrappers through the gymnasium.make() function. To do this, the environment must be registered prior with gymnasium.register(). To get the environment specifications for a registered environment, use gymnasium.spec() and to print the whole registry, use gymnasium.pprint_registry().

gymnasium.make(id: str | EnvSpec, max_episode_steps: int | None = None, autoreset: bool | None = None, apply_api_compatibility: bool | None = None, disable_env_checker: bool | None = None, **kwargs: Any) Env[source]#

Creates an environment previously registered with gymnasium.register() or a EnvSpec.

To find all available environments use gymnasium.envs.registry.keys() for all valid ids.

  • id – A string for the environment id or a EnvSpec. Optionally if using a string, a module to import can be included, e.g. 'module:Env-v0'. This is equivalent to importing the module first to register the environment followed by making the environment.

  • max_episode_steps – Maximum length of an episode, can override the registered EnvSpec max_episode_steps. The value is used by gymnasium.wrappers.TimeLimit.

  • autoreset – Whether to automatically reset the environment after each episode (gymnasium.wrappers.AutoResetWrapper).

  • apply_api_compatibility – Whether to wrap the environment with the gymnasium.wrappers.StepAPICompatibility wrapper that converts the environment step from a done bool to return termination and truncation bools. By default, the argument is None in which the EnvSpec apply_api_compatibility is used, otherwise this variable is used in favor.

  • disable_env_checker – If to add gymnasium.wrappers.PassiveEnvChecker, None will default to the EnvSpec disable_env_checker value otherwise use this value will be used.

  • kwargs – Additional arguments to pass to the environment constructor.


An instance of the environment with wrappers applied.


Error – If the id doesn’t exist in the registry

gymnasium.register(id: str, entry_point: EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, autoreset: bool = False, disable_env_checker: bool = False, apply_api_compatibility: bool = False, additional_wrappers: tuple[WrapperSpec, ...] = (), vector_entry_point: VectorEnvCreator | str | None = None, **kwargs: Any)[source]#

Registers an environment in gymnasium with an id to use with gymnasium.make() with the entry_point being a string or callable for creating the environment.

The id parameter corresponds to the name of the environment, with the syntax as follows: [namespace/](env_name)[-v(version)] where namespace and -v(version) is optional.

It takes arbitrary keyword arguments, which are passed to the EnvSpec kwargs parameter.

  • id – The environment id

  • entry_point – The entry point for creating the environment

  • reward_threshold – The reward threshold considered for an agent to have learnt the environment

  • nondeterministic – If the environment is nondeterministic (even with knowledge of the initial seed and all actions, the same state cannot be reached)

  • max_episode_steps – The maximum number of episodes steps before truncation. Used by the gymnasium.wrappers.TimeLimit wrapper if not None.

  • order_enforce – If to enable the order enforcer wrapper to ensure users run functions in the correct order. If True, then the gymnasium.wrappers.OrderEnforcing is applied to the environment.

  • autoreset – If to add the gymnasium.wrappers.AutoResetWrapper such that on (terminated or truncated) is True, gymnasium.Env.reset() is called.

  • disable_env_checker – If to disable the gymnasium.wrappers.PassiveEnvChecker to the environment.

  • apply_api_compatibility – If to apply the gymnasium.wrappers.StepAPICompatibility wrapper to the environment. Use if the environment is implemented in the gym v0.21 environment API.

  • additional_wrappers – Additional wrappers to apply the environment.

  • vector_entry_point – The entry point for creating the vector environment

  • **kwargs – arbitrary keyword arguments which are passed to the environment constructor on initialisation.

gymnasium.spec(env_id: str) EnvSpec[source]#

Retrieve the EnvSpec for the environment id from the registry.


env_id – The environment id with the expected format of [(namespace)/]id[-v(version)]


The environment spec if it exists


Error – If the environment id doesn’t exist

gymnasium.pprint_registry(print_registry: dict[str, EnvSpec] = registry, *, num_cols: int = 3, exclude_namespaces: list[str] | None = None, disable_print: bool = False) str | None[source]#

Pretty prints all environments in the registry.


All arguments are keyword only

  • print_registry – Environment registry to be printed. By default, registry

  • num_cols – Number of columns to arrange environments in, for display.

  • exclude_namespaces – A list of namespaces to be excluded from printing. Helpful if only ALE environments are wanted.

  • disable_print – Whether to return a string of all the namespaces and environment IDs or to print the string to console.

Core variables#

class gymnasium.envs.registration.EnvSpec(id: str, entry_point: EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, autoreset: bool = False, disable_env_checker: bool = False, apply_api_compatibility: bool = False, kwargs: dict = <factory>, additional_wrappers: tuple[WrapperSpec, ...] = <factory>, vector_entry_point: VectorEnvCreator | str | None = None)[source]#

A specification for creating environments with gymnasium.make().

  • id: The string used to create the environment with gymnasium.make()

  • entry_point: A string for the environment location, (import path):(environment name) or a function that creates the environment.

  • reward_threshold: The reward threshold for completing the environment.

  • nondeterministic: If the observation of an environment cannot be repeated with the same initial state, random number generator state and actions.

  • max_episode_steps: The max number of steps that the environment can take before truncation

  • order_enforce: If to enforce the order of gymnasium.Env.reset() before gymnasium.Env.step() and gymnasium.Env.render() functions

  • autoreset: If to automatically reset the environment on episode end

  • disable_env_checker: If to disable the environment checker wrapper in gymnasium.make(), by default False (runs the environment checker)

  • kwargs: Additional keyword arguments passed to the environment during initialisation

  • additional_wrappers: A tuple of additional wrappers applied to the environment (WrapperSpec)

  • vector_entry_point: The location of the vectorized environment to create from


The Global registry for gymnasium which is where environment specifications are stored by gymnasium.register() and from which gymnasium.make() is used to create environments.


The current namespace when creating or registering environments. This is by default None by with namespace() this can be modified to automatically set the environment id namespace.

Additional functions#

gymnasium.envs.registration.get_env_id(ns: str | None, name: str, version: int | None) str[source]#

Get the full env ID given a name and (optional) version and namespace. Inverse of parse_env_id().

  • ns – The environment namespace

  • name – The environment name

  • version – The environment version


The environment id

gymnasium.envs.registration.parse_env_id(env_id: str) tuple[str | None, str, int | None][source]#

Parse environment ID string format - [namespace/](env-name)[-v(version)] where the namespace and version are optional.


env_id – The environment id to parse


A tuple of environment namespace, environment name and version number


Error – If the environment id is not valid environment regex

gymnasium.envs.registration.find_highest_version(ns: str | None, name: str) int | None[source]#

Finds the highest registered version of the environment given the namespace and name in the registry.

  • ns – The environment namespace

  • name – The environment name (id)


The highest version of an environment with matching namespace and name, otherwise ``None`` is returned.

gymnasium.envs.registration.namespace(ns: str)[source]#

Context manager for modifying the current namespace.

gymnasium.envs.registration.load_env_creator(name: str) EnvCreator | VectorEnvCreator[source]#

Loads an environment with name of style "(import path):(environment name)" and returns the environment creation function, normally the environment class type.


name – The environment name


The environment constructor for the given environment name.

gymnasium.envs.registration.load_plugin_envs(entry_point: str = 'gymnasium.envs')[source]#

Load modules (plugins) using the gymnasium entry points in order to register external module’s environments on import gymnasium.


entry_point – The string for the entry point.