Wrappers¶

Wrappers are a convenient way to modify an existing environment without having to alter the underlying code directly.

Using wrappers will allow you to avoid a lot of boilerplate code and make your environment more modular. Importantly wrappers can be chained to combine their effects and most environments that are generated via gymnasium.make() will already be wrapped by default.

In order to wrap an environment, you must first initialize a base environment. Then you can this environment along with (possibly optional) parameters to the wrapper’s constructor.

           >>> import gymnasium as gym
>>> from gymnasium.wrappers import RescaleAction
>>> base_env = gym.make("Hopper-v4")
>>> base_env.action_space
Box(-1.0, 1.0, (3,), float32)
>>> wrapped_env = RescaleAction(base_env, min_action=0, max_action=1)
>>> wrapped_env.action_space
Box(0.0, 1.0, (3,), float32)

          

You can access the environment underneath the first wrapper by using the gymnasium.Wrapper.env can be another wrapper.

           >>> wrapped_env
<RescaleAction<TimeLimit<OrderEnforcing<iveEnvChecker<HopperEnv<Hopper-v4>>>>>>
>>> wrapped_env.env
<TimeLimit<OrderEnforcing<iveEnvChecker<HopperEnv<Hopper-v4>>>>>

          

If you want to get to the environment underneath all of the layers of wrappers, you can use the gymnasium.Wrapper.unwrapped attribute will just return itself.

           >>> wrapped_env
<RescaleAction<TimeLimit<OrderEnforcing<iveEnvChecker<HopperEnv<Hopper-v4>>>>>>
>>> wrapped_env.unwrapped 
<gymnasium.envs.mujoco.hopper_v4.HopperEnv object at 0x7fbb5efd0490>

          

There are three common things you might want a wrapper to do:

Transform actions before applying them to the base environment
Transform observations that are returned by the base environment
Transform rewards that are returned by the base environment

Such wrappers can be easily implemented by inheriting from gymnasium.Wrapper class directly.

If you’d like to implement your own custom wrapper, check out the corresponding tutorial.

class gymnasium.Wrapper(env: ¶: Wraps a reset() methods.

This class is the base class of all wrappers to change the behavior of the underlying environment. Wrappers that inherit from this class can modify the reset() methods can be changed by these wrappers.

Some attributes (env).

Note

If you inherit from Wrapper, don’t forget to call super().__init__(env)

Parameters:

env – The environment to wrap

Methods¶

Wrapper.step(action: WrapperActType) → tuple[WrapperObsType, sFloat, bool, bool, dict[str, Any]]¶

Uses the env that can be overwritten to change the returned data.

Wrapper.reset(*, seed: int | None = None, options: dict[str, Any] | None = None) → tuple[WrapperObsType, dict[str, Any]]¶

Uses the env that can be overwritten to change the returned data.

Wrapper.render() → RenderFrame | list[RenderFrame] | None¶

Uses the env that can be overwritten to change the returned data.

Wrapper.close()¶

Closes the wrapper and env.

classmethod Wrapper.wrapper_spec(**kwargs: Any) → ¶

Generates a WrapperSpec for the wrappers.

Wrapper.get_wrapper_attr(name: str) → Any¶

Gets an attribute from the wrapper and lower environments if name doesn’t exist in this object.

Parameters:

name – The variable name to get

Returns:

The variable with name in wrapper or lower environments

Wrapper.set_wrapper_attr(name: str, value: Any, *, force: bool = True) → bool¶

Sets an attribute on this wrapper or lower environment if name is already defined.

Parameters:

name – The variable name

value – The new variable value

force – Whether to create the attribute on this wrapper if it does not exists on the lower environment instead of raising an exception

Returns:

If the variable has been set in this or a lower wrapper.

Attributes¶

Wrapper.env¶

The environment (one level underneath) this wrapper.

This may itself be a wrapped environment. To obtain the environment underneath all layers of wrappers, use gymnasium.Wrapper.unwrapped.

property Wrapper.action_space: ¶

Return the action_space is used.

property Wrapper.observation_space: ¶

Return the observation_space is used.

property Wrapper.spec: ¶

Returns the spec attribute with the WrapperSpec if the wrapper inherits from EzPickle.

property Wrapper.metadata: dict[str, Any]¶

Returns the metadata.

property Wrapper.np_random: Generator¶

Returns the np_random attribute.

property Wrapper.np_random_seed: int | None¶

Returns the base environment’s np_random_seed.

property Wrapper.unwrapped: ¶

Returns the base environment of the wrapper.

This will be the bare gymnasium.Env environment, underneath all layers of wrappers.