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.

Parameters:

  • 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.

Returns:

An instance of the environment with wrappers applied.

Raises:

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.

Parameters:

  • 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.

Parameters:

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

Returns:

The environment spec if it exists

Raises:

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.

Note

All arguments are keyword only

Parameters:

  • 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

gymnasium.envs.registration.registry#

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.

gymnasium.envs.registration.current_namespace#

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

Parameters:

  • ns – The environment namespace

  • name – The environment name

  • version – The environment version

Returns:

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.

Parameters:

env_id – The environment id to parse

Returns:

A tuple of environment namespace, environment name and version number

Raises:

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.

Parameters:

  • ns – The environment namespace

  • name – The environment name (id)

Returns:

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.

Parameters:

name – The environment name

Returns:

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.

Parameters:

entry_point – The string for the entry point.