Table of Contents

Class EnvRegistry

Namespace
Gym.Envs.Registration
Assembly
Gym.dll

Gymnasium's gymnasium.envs.registration module: the id grammar, the process-wide Registry, Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?), Spec(string), Make(string, object?, long?, bool?) and PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool). The top-level Gymnasium class re-exports them, as gymnasium.make re-exports gymnasium.envs.registration.make.

public static class EnvRegistry
Inheritance
EnvRegistry
Inherited Members

Remarks

Properties

CurrentNamespace

The namespace Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?) puts ids in, overriding the id's own (Python's module global current_namespace); null keeps each id's namespace. Set it through Namespace(string), which restores it.

public static string? CurrentNamespace { get; set; }

Property Value

string

Remarks

Unlike Python's module global, the value belongs to the current thread and async flow (an AsyncLocal<T>, DR-57): two threads registering inside scopes of their own at the same moment each get their own namespace, where one global would hand both the namespace opened last. A thread, task or async continuation started inside a scope inherits its value as it was at the start. On one thread it behaves as Gymnasium's global does. Footgun: a value set inside an async method does not flow back to its caller once the method returns (how AsyncLocal<T> works), so open the scope in the code that registers rather than in a helper it awaits.

Registry

The global registry (Python's gymnasium.registry): every id make knows, in registration order. Env assemblies fill it from their module initializers (DR-12); Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?) adds to it.

public static EnvSpecRegistry Registry { get; }

Property Value

EnvSpecRegistry

Methods

EntryPointName(Type)

The "Namespace:Class" string that names a class as an entry point, the form load_env_creator reads back: "Gym.Environments.Envs.Classic:CartPoleEnv", a generic class without its arity ("Gym.Wrappers:TimeLimit"). A spec's JSON writes a class entry point this way.

public static string EntryPointName(Type type)

Parameters

type Type

The class.

Returns

string

The entry-point string.

Exceptions

ArgumentNullException

Thrown when type is null.

FindHighestVersion(string?, string)

The highest registered version of name in ns (Python's find_highest_version), which make uses for an id given without a version.

public static long? FindHighestVersion(string? ns, string name)

Parameters

ns string

The namespace, or null.

name string

The env name.

Returns

long?

The version, or null when no versioned id of that name is registered.

Remarks

GetEnvId(string?, string, long?)

Joins a namespace, name and version into an id, the inverse of ParseEnvId(string): ("ALE", "Pong", 5) is "ALE/Pong-v5".

public static string GetEnvId(string? ns, string name, long? version)

Parameters

ns string

The namespace, or null.

name string

The name.

version long?

The version, or null.

Returns

string

The id.

Remarks

LoadEnvCreator(string)

The class a "Namespace:Class" entry point names (Python's load_env_creator, which imports module and reads its attribute): a class of that name in that namespace among the loaded assemblies, after loading the assembly named by the namespace (or a prefix of it) when none declares it yet.

public static Type LoadEnvCreator(string name)

Parameters

name string

The entry point, "Gym.Wrappers:TimeLimit"; a generic class is named without its arity.

Returns

Type

The class (an open generic definition for a generic one).

Remarks

Exceptions

ArgumentNullException

Thrown when name is null.

ValueError

Thrown when the string has no colon or more than one (Python's unpacking: not enough values to unpack (expected 2, got 1)).

ModuleNotFoundError

Thrown when no loaded or loadable assembly declares the namespace: No module named 'X'.

AttributeError

Thrown when the namespace has no such class: module 'X' has no attribute 'Y'.

Make(EnvSpec, object?, long?, bool?)

Builds the env a spec describes, with make's wrappers (Python's make(env_spec)); see Make(string, object?, long?, bool?).

public static IEnv Make(EnvSpec spec, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec, registered or not (one read back from JSON, for example).

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env; the caller owns it.

Exceptions

TypeError

Thrown when spec is null, or as Make(string, object?, long?, bool?) does.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make(string, object?, long?, bool?)

Builds the env registered under id with make's wrappers (Python's make): the env, then PassiveEnvChecker (unless disabled), OrderEnforcing (when the spec enforces order), TimeLimit (when a step limit applies), the spec's additional wrappers, and RenderCollection for a *_list render mode the env does not provide itself.

public static IEnv Make(string id, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id: "CartPole-v1", an unversioned "CartPole" (the latest version, with a warning), or "Assembly:Id", which first loads the assembly and runs its registration, as Python imports the module.

kwargs object

The env's constructor arguments by Python name, over the spec's: a dictionary, an options record, or an anonymous object (new { render_mode = "rgb_array" }).

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit at all.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

IEnv

The env, through its untyped view; the caller owns it.

Remarks

The env and every wrapper are built through Construct(Type, IReadOnlyDictionary<string, object?>), which binds keywords by Python name and closes the generic wrappers over the env's types. When a step after the env's construction fails (a wrapper refusing the env), the env built so far is disposed before the error propagates.

Where an env lists both rgb_array and rgb_array_list and human is asked for, Python picks either by its set order; Gym.NET always renders rgb_array for the HumanRendering wrapper.

Reference: gymnasium/envs/registration.py.

Exceptions

TypeError

Thrown when id is null, when the env's constructor rejects the kwargs (CartPoleEnv.init() got an unexpected keyword argument 'x' was raised from the environment creator for CartPole-v1 with kwargs ({'x': 1})), or when the entry point does not build an env.

Error

Thrown when the id is not registered or has no entry point, with Gymnasium's messages.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when an "Assembly:Id" or a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created, or a pre-applied wrapper disagrees with the spec.

MakeVec(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env from a spec (gymnasium.make_vec(env_spec)); see MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?).

public static IVectorEnv MakeVec(EnvSpec spec, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

spec EnvSpec

The spec: a registered one, or one a previous MakeVec recorded (its num_envs, mode, vector kwargs and wrappers win).

numEnvs int

The number of sub-envs.

vectorizationMode object

The vectorization mode, or null.

vectorKwargs object

The vector env's constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

Returns

IVectorEnv

The vector env; the caller owns it.

Exceptions

TypeError

Thrown when spec is null, or the env cannot be built.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the spec has no (vector) entry point, or the vector entry point is asked for with vector kwargs or wrappers.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

Builds a vector env of numEnvs copies of a registered env (gymnasium.make_vec): its own vectorized class when the spec has a vector_entry_point (CartPoleVectorEnv), else a SyncVectorEnv of Make's stacks. The result is untyped (observations and actions as objects); MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?) types it.

public static IVectorEnv MakeVec(string id, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs; a spec made by MakeVec records its own, which wins.

vectorizationMode object

A VectorizeMode or its value ("sync", "async", "vector_entry_point"); null picks the vector entry point when the spec has one, else sync.

vectorKwargs object

The vector env's constructor arguments by Python name (autoreset_mode, copy, observation_mode; for async also shared_memory, max_concurrency, execution_mode, thread_count); sync and async only.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env after Make, innermost first; sync and async only.

kwargs object

The env's constructor arguments by Python name, over the spec's.

Returns

IVectorEnv

The vector env, its spec recording how it was made; the caller owns it.

Remarks

Exceptions

TypeError

Thrown when id is null, or the env cannot be built from the kwargs.

ValueError

Thrown for an unknown vectorization mode, with Gymnasium's message.

Error

Thrown when the id is not registered, has no (vector) entry point, or the vector entry point is asked for with vector kwargs or wrappers.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(EnvSpec, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(EnvSpec spec, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

spec EnvSpec

The spec.

numEnvs int

The number of sub-envs.

vectorizationMode object

The vectorization mode, or null.

vectorKwargs object

The vector env's constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type.

TAct

The batched action type.

Exceptions

TypeError

Thrown when spec is null or the batched types differ.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the spec has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

MakeVec<TObs, TAct>(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?)

MakeVec(string, int, object?, object?, IEnumerable<Func<IEnv, IEnv>>?, object?) typed (DR-21): the vector env comes back as VectorEnv<TObs, TAct> of the batched types, a sync one built as SyncVectorEnv<TObs, TAct>.

public static VectorEnv<TObs, TAct> MakeVec<TObs, TAct>(string id, int numEnvs = 1, object? vectorizationMode = null, object? vectorKwargs = null, IEnumerable<Func<IEnv, IEnv>>? wrappers = null, object? kwargs = null)

Parameters

id string

The id.

numEnvs int

The number of sub-envs.

vectorizationMode object

The vectorization mode, or null.

vectorKwargs object

The vector env's constructor arguments by Python name.

wrappers IEnumerable<Func<IEnv, IEnv>>

Wrappers applied to every sub-env.

kwargs object

The env's constructor arguments by Python name.

Returns

VectorEnv<TObs, TAct>

The vector env; the caller owns it.

Type Parameters

TObs

The batched observation type (NDArray for array spaces).

TAct

The batched action type.

Exceptions

TypeError

Thrown when the vector env's batched types are not the ones asked for, or as the untyped form throws.

ValueError

Thrown for an unknown vectorization mode.

Error

Thrown when the id is not registered or has no (vector) entry point.

RuntimeError

Thrown when a sub-env's spaces do not fit the batch (sync and async modes).

Make<TObs, TAct>(EnvSpec, object?, long?, bool?)

public static Env<TObs, TAct> Make<TObs, TAct>(EnvSpec spec, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

spec EnvSpec

The spec.

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have.

TAct

The action type the env must have.

Exceptions

TypeError

Thrown when spec is null or the env is not an Env<TObs, TAct>.

Error

Thrown when the spec has no entry point.

ModuleNotFoundError

Thrown when a string entry point names a module that does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Make<TObs, TAct>(string, object?, long?, bool?)

Make(string, object?, long?, bool?) typed (DR-10): the env comes back as Env<TObs, TAct>. An env class of other types is refused before it is built; a stack whose recorded wrappers change the types is checked once built.

public static Env<TObs, TAct> Make<TObs, TAct>(string id, object? kwargs = null, long? maxEpisodeSteps = null, bool? disableEnvChecker = null)

Parameters

id string

The id.

kwargs object

The env's constructor arguments by Python name, over the spec's.

maxEpisodeSteps long?

The step limit instead of the spec's; -1 adds no TimeLimit.

disableEnvChecker bool?

Whether to leave out PassiveEnvChecker; null follows the spec.

Returns

Env<TObs, TAct>

The env; the caller owns it.

Type Parameters

TObs

The observation type the env must have (NDArray for CartPole).

TAct

The action type the env must have (NDArray for a Discrete action, DR-08).

Exceptions

TypeError

Thrown when the env is not an Env<TObs, TAct>, or as Make(string, object?, long?, bool?) does.

Error

Thrown when the id is not registered or has no entry point.

NamespaceNotFound

Thrown when the id's namespace is unknown.

NameNotFound

Thrown when the name is unknown.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest.

ModuleNotFoundError

Thrown when a module named by the id or the entry point does not exist.

AttributeError

Thrown when a string entry point's namespace has no such class.

InvalidMetadata

Thrown when the env class's ClassMetadata is not a dict.

ValueError

Thrown when a recorded wrapper cannot be re-created.

Namespace(string)

Sets CurrentNamespace until the returned scope is disposed (Python's namespace context manager): using (EnvRegistry.Namespace("MyPlugin")) Register("Env-v0", ...); registers MyPlugin/Env-v0. Inside the scope every id lands in ns, even one that names a namespace of its own, as in Gymnasium.

public static IDisposable Namespace(string ns)

Parameters

ns string

The namespace.

Returns

IDisposable

The scope; disposing it restores the namespace that was current before, once.

Remarks

The scope applies to the thread and async flow that opened it, and to the threads and tasks started inside it (DR-57); other threads keep their own namespace. Reference: gymnasium/envs/registration.py.

ParseEnvId(string)

Splits an id into its namespace, name and version, the inverse of GetEnvId(string?, string, long?). "ALE/Pong-v5" is ("ALE", "Pong", 5); "CartPole" is (null, "CartPole", null).

public static (string? Namespace, string Name, long? Version) ParseEnvId(string envId)

Parameters

envId string

The id.

Returns

(string Namespace, string Name, long? Version)

The namespace (or null), the name, and the version (or null).

Remarks

Exceptions

ArgumentNullException

Thrown when envId is null.

Error

Thrown when the id does not match, with Gymnasium's message: Malformed environment ID: {env_id}. (Currently all IDs must be of the form namespace/-v(version). (namespace is optional)).

OverflowException

Thrown for a version beyond long, which Python's unbounded int would hold.

PprintRegistry(IReadOnlyDictionary<string, EnvSpec>?, int, IEnumerable<string?>?, bool)

Prints (or returns) every registered id grouped by namespace (Python's pprint_registry): a ===== namespace ===== header, then the ids sorted, numCols to a line.

public static string? PprintRegistry(IReadOnlyDictionary<string, EnvSpec>? printRegistry = null, int numCols = 3, IEnumerable<string?>? excludeNamespaces = null, bool disablePrint = false)

Parameters

printRegistry IReadOnlyDictionary<string, EnvSpec>

The registry to print; null is Registry.

numCols int

How many ids per line.

excludeNamespaces IEnumerable<string>

Namespaces to leave out, or null.

disablePrint bool

Return the text instead of writing it to the console.

Returns

string

The text when disablePrint is set, otherwise null.

Remarks

An id without a namespace is grouped by its entry point, as in Gymnasium: a string "gymnasium.envs.classic_control.cartpole:CartPoleEnv" by its third dotted part (classic_control), else its second, else the env's name; a function by None. A class entry point, which Python groups under None too, is grouped here by the last part of its namespace, the env family (Classic for Gym.Environments.Envs.Classic), so Gym.NET's own ids print in families. Reference: gymnasium/envs/registration.py.

Exceptions

ZeroDivisionError

Thrown when numCols is 0 (Python's ZeroDivisionError).

Register(string, object?, double?, bool, long?, bool, bool, IEnumerable<WrapperSpec>?, object?, object?)

Registers an env under id for make (Python's register). The id's namespace is replaced by CurrentNamespace when one is set; re-registering an id replaces it with a warning.

public static void Register(string id, object? entryPoint = null, double? rewardThreshold = null, bool nondeterministic = false, long? maxEpisodeSteps = null, bool orderEnforce = true, bool disableEnvChecker = false, IEnumerable<WrapperSpec>? additionalWrappers = null, object? vectorEntryPoint = null, object? kwargs = null)

Parameters

id string

The id, namespace/[-v(version)].

entryPoint object

What builds the env: its class (typeof(CartPoleEnv)), an EnvCreator, or a "Namespace:Class" string resolved when the env is made.

rewardThreshold double?

The return at which the task counts as solved.

nondeterministic bool

Whether the same seed and actions can still give different observations.

maxEpisodeSteps long?

The step limit make's TimeLimit enforces, or null for none.

orderEnforce bool

Whether make adds OrderEnforcing.

disableEnvChecker bool

Whether make leaves out PassiveEnvChecker.

additionalWrappers IEnumerable<WrapperSpec>

Wrappers make applies on top, in order.

vectorEntryPoint object

What builds a vectorized version (for make_vec).

kwargs object

The env's constructor arguments by Python name: a dictionary (an Info is kept as the spec's own, as Python keeps the dict passed), an options record, or an anonymous object.

Remarks

Exceptions

ValueError

Thrown when neither entry point is given: Either entry_point or vector_entry_point (or both) must be provided.

Error

Thrown for a malformed id.

RegistrationError

Thrown when a versioned and an unversioned id of the same name would both be registered, with Gymnasium's messages.

TypeError

Thrown when kwargs is not a mapping.

RegisterEnvs(object?)

A no-op that marks a module as used (Python's register_envs), kept so code written against Gymnasium reads the same. Registering an env assembly's ids is its Register()'s job, which a module initializer calls (DR-12, DR-17).

public static void RegisterEnvs(object? envModule)

Parameters

envModule object

Anything; ignored.

Remarks

Spec(string)

The spec registered under envId (Python's spec), without the version and namespace fallbacks of make: the id must be registered exactly.

public static EnvSpec Spec(string envId)

Parameters

envId string

The id.

Returns

EnvSpec

The registered spec itself (not a copy).

Remarks

Exceptions

ArgumentNullException

Thrown when envId is null.

Error

Thrown for a malformed id, or one that is not registered (No registered env with id: X).

NamespaceNotFound

Thrown when the id's namespace is unknown (with a suggestion when one is close).

NameNotFound

Thrown when the name is unknown in its namespace.

VersionNotFound

Thrown when the version is newer than any registered.

DeprecatedEnv

Thrown when the version is older than the latest, or only an unversioned id exists.