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

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)#

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#

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#

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)#

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#

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]#

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#

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)#: Context manager for modifying the current namespace.

gymnasium.envs.registration.load_env_creator(name: str) → EnvCreator | VectorEnvCreator#

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')#

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.