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

gymnasium.make_vec(id: str | EnvSpec, num_envs: int = 1, vectorization_mode: VectorizeMode | str | None = None, vector_kwargs: dict[str, Any] | None = None, wrappers: Sequence[Callable[[Env], Wrapper]] | None = None, **kwargs) → gym.vector.VectorEnv[source]¶

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.