Implementation:Farama Foundation Gymnasium Vector RecordEpisodeStatistics

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

Overview

Concrete tool for tracking per-environment episode statistics in vectorized environments provided by the Gymnasium library.

Description

The vector version of RecordEpisodeStatistics wraps a VectorEnv and tracks cumulative rewards and episode lengths for each sub-environment independently. When any sub-environment finishes an episode, the statistics are appended to the shared return_queue and length_queue. Episode data is also injected into the batched infos dict with the "episode" key.

Usage

Wrap vectorized environments when training with deep RL algorithms to monitor learning progress across all parallel environments.

Code Reference

Source Location

• Repository: Gymnasium
• File: gymnasium/wrappers/vector/common.py
• Lines: L22-195

Signature

class RecordEpisodeStatistics(VectorWrapper):
    def __init__(
        self,
        env: VectorEnv,
        buffer_length: int = 100,
        stats_key: str = "episode",
    ):
        """Track episode statistics for vectorized environments.

        Args:
            env: The vector environment to wrap.
            buffer_length: Size of return_queue and length_queue buffers.
            stats_key: Info dict key for episode statistics.
        """

Import

from gymnasium.wrappers.vector import RecordEpisodeStatistics
import gymnasium as gym

envs = gym.make_vec("CartPole-v1", num_envs=4)
envs = RecordEpisodeStatistics(envs)

I/O Contract

Inputs

Name	Type	Required	Description
env	VectorEnv	Yes	Vectorized environment to wrap
buffer_length	int	No	Deque buffer size (default 100)
stats_key	str	No	Info key for statistics (default "episode")

Outputs

Name	Type	Description
return_queue	deque[float]	Rolling episode returns across all sub-envs
length_queue	deque[int]	Rolling episode lengths across all sub-envs
infos["episode"]	dict	Per-env episode stats when episodes complete

Usage Examples

Vector Training Monitoring

import gymnasium as gym
from gymnasium.wrappers.vector import RecordEpisodeStatistics

envs = gym.make_vec("CartPole-v1", num_envs=8)
envs = RecordEpisodeStatistics(envs, buffer_length=50)

obs, infos = envs.reset(seed=42)

for step in range(10000):
    actions = envs.action_space.sample()
    obs, rewards, terms, truncs, infos = envs.step(actions)

# Check rolling statistics
if len(envs.return_queue) > 0:
    avg_return = sum(envs.return_queue) / len(envs.return_queue)
    print(f"Average return: {avg_return:.2f}")

envs.close()

Related Pages

Implements Principle

• Principle:Farama_Foundation_Gymnasium_Vector_Episode_Statistics

Requires Environment

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime