Implementation:Farama Foundation Gymnasium Vector NormalizeObservation

Knowledge Sources	Farama_Foundation_Gymnasium Gymnasium Docs
Domains	Reinforcement_Learning, Wrappers
Last Updated	2026-02-15 03:00 GMT

Overview

A vector observation wrapper that normalizes observations across all sub-environments to be centered at the mean with unit variance using a shared RunningMeanStd tracker.

Description

The NormalizeObservation vector wrapper normalizes observations from a vectorized environment so that each coordinate is approximately centered with unit variance. It uses a single RunningMeanStd instance shared across all sub-environments.

Key features:

• Shared statistics -- A single RunningMeanStd tracker is updated with all sub-environment observations, providing more stable statistics than per-environment tracking.
• Float32 output -- The observation space is transformed to Box(-inf, inf) with float32 dtype. Normalized observations are cast to float32.
• Freeze support -- The update_running_mean property can be set to False to freeze statistics during evaluation.
• Autoreset handling -- Only supports NEXT_STEP autoreset mode and does not support partial resets.

The normalization formula is: (observation - mean) / sqrt(var + epsilon)

Usage

Use this wrapper for training with vectorized environments when observations need to be normalized. The shared statistics across sub-environments provide faster convergence of the running mean/variance estimates compared to the single-environment version.

Code Reference

Source Location

• Repository: Farama_Foundation_Gymnasium
• File: gymnasium/wrappers/vector/stateful_observation.py

Signature

class NormalizeObservation(VectorObservationWrapper, gym.utils.RecordConstructorArgs):
    def __init__(self, env: VectorEnv, epsilon: float = 1e-8): ...

Import

from gymnasium.wrappers.vector import NormalizeObservation

I/O Contract

Inputs

Name	Type	Required	Description
env	VectorEnv	Yes	The vector environment to wrap
epsilon	float	No	Stability parameter for normalization (default 1e-8)

Outputs

Name	Type	Description
observations	ndarray (float32)	Normalized observations centered with unit variance

Usage Examples

import numpy as np
import gymnasium as gym
from gymnasium.wrappers.vector import NormalizeObservation

envs = gym.make_vec("CartPole-v1", num_envs=3, vectorization_mode="sync")
envs = NormalizeObservation(envs)

obs, info = envs.reset(seed=123)
_ = envs.action_space.seed(123)

for _ in range(100):
    obs, *_ = envs.step(envs.action_space.sample())

np.mean(obs)   # approximately 0
np.std(obs)    # approximately 1

# Freeze statistics for evaluation
envs.update_running_mean = False

envs.close()

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime