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

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

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)

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

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, disable_env_checker: 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

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

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

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.