Make and register¶

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, 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 with the value being passed to gymnasium.wrappers.TimeLimit. Using max_episode_steps=-1 will not apply the wrapper to the environment.
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

Changelogs:: v1.0.0 - autoreset and apply_api_compatibility was removed

Create a vector environment according to the given ID.

To find all available environments use gymnasium.pprint_registry() or gymnasium.registry.keys() for all valid ids. We refer to the Vector environment as the vectorizor while the environment being vectorized is the base or vectorized environment (vectorizor(vectorized env)).

Parameters:

id – Name of the environment. Optionally, a module to import can be included, e.g. ‘module:Env-v0’
num_envs – Number of environments to create
vectorization_mode – The vectorization method used, defaults to None such that if env id’ spec has a vector_entry_point (not None), this is first used otherwise defaults to sync to use the gymnasium.vector.SyncVectorEnv. Valid modes are "async", "sync" or "vector_entry_point". Recommended to use the VectorizeMode enum rather than strings.
vector_kwargs – Additional arguments to pass to the vectorizor environment constructor, i.e., SyncVectorEnv(..., **vector_kwargs).
wrappers – A sequence of wrapper functions to apply to the base environment. Can only be used in "sync" or "async" mode.
**kwargs – Additional arguments passed to the base environment constructor.

Returns:

An instance of the environment.

Raises:

Error – If the id doesn’t exist then an error is raised

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, disable_env_checker: bool = False, additional_wrappers: tuple[WrapperSpec, ...] = (), vector_entry_point: VectorEnvCreator | str | None = None, kwargs: dict | None = None)[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.
disable_env_checker – If to disable the gymnasium.wrappers.PassiveEnvChecker to the environment.
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.

Changelogs:: v1.0.0 - autoreset and apply_api_compatibility parameter was removed

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: ~gymnasium.envs.registration.EnvCreator | str | None = None, reward_threshold: float | None = None, nondeterministic: bool = False, max_episode_steps: int | None = None, order_enforce: bool = True, disable_env_checker: bool = False, kwargs: dict = <factory>, additional_wrappers: tuple[~gymnasium.envs.registration.WrapperSpec, ...] = <factory>, vector_entry_point: ~gymnasium.envs.registration.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
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

Changelogs:: v1.0.0 - Autoreset attribute removed

class gymnasium.envs.registration.WrapperSpec(name: str, entry_point: str, kwargs: dict[str, Any] | None)[source]¶

A specification for recording wrapper configs.

name: The name of the wrapper.
entry_point: The location of the wrapper to create from.
kwargs: Additional keyword arguments passed to the wrapper. If the wrapper doesn’t inherit from EzPickle then this is None

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.