Implementation:Farama Foundation Gymnasium Step Api Compatibility

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

Overview

Provides bidirectional conversion functions between the old (done-based) and new (terminated/truncated-based) Gymnasium step API formats.

Description

The step_api_compatibility module handles the transition between two versions of the Gymnasium step API:

• Old API (done-based): (obs, reward, done, info) where done is a single boolean and truncation information is stored in info["TimeLimit.truncated"].
• New API (terminated/truncated-based): (obs, reward, terminated, truncated, info) with explicit separate booleans for termination and truncation.

The module provides three functions:

convert_to_terminated_truncated_step_api converts 4-tuple (old) returns to 5-tuple (new) format. For single environments, it extracts TimeLimit.truncated from the info dict and computes the separated booleans. For vector environments, it handles both list-of-dicts and dict-of-arrays info formats using np.logical_and and np.logical_not operations.

convert_to_done_step_api converts 5-tuple (new) returns to 4-tuple (old) format, combining terminated and truncated into a single done boolean and storing truncation info in info["TimeLimit.truncated"].

step_api_compatibility is the main entry point that dispatches to either conversion function based on the output_truncation_bool parameter.

Usage

Use these functions when working with environments or wrappers that use a different step API version than expected, or when building compatibility layers between old and new Gymnasium code.

Code Reference

Source Location

• Repository: Farama_Foundation_Gymnasium
• File: gymnasium/utils/step_api_compatibility.py

Signature

def step_api_compatibility(
    step_returns: TerminatedTruncatedStepType | DoneStepType,
    output_truncation_bool: bool = True,
    is_vector_env: bool = False,
) -> TerminatedTruncatedStepType | DoneStepType

def convert_to_terminated_truncated_step_api(
    step_returns: DoneStepType | TerminatedTruncatedStepType,
    is_vector_env=False,
) -> TerminatedTruncatedStepType

def convert_to_done_step_api(
    step_returns: TerminatedTruncatedStepType | DoneStepType,
    is_vector_env: bool = False,
) -> DoneStepType

Import

from gymnasium.utils.step_api_compatibility import (
    step_api_compatibility,
    convert_to_terminated_truncated_step_api,
    convert_to_done_step_api,
)

I/O Contract

Inputs

Name	Type	Required	Description
step_returns	tuple	Yes	Step output in either 4-tuple or 5-tuple format
output_truncation_bool	bool	No	If True, output new API (5-tuple); if False, output old API (4-tuple). Default True.
is_vector_env	bool	No	Whether the step returns are from a vector environment (default False)

Outputs

Name	Type	Description
step_returns	tuple	Converted step output in the requested format (4-tuple or 5-tuple)

Usage Examples

import gymnasium as gym
from gymnasium.utils.step_api_compatibility import step_api_compatibility

env = gym.make("CartPole-v0")
_, _ = env.reset()

# Convert to old API (4-tuple)
obs, reward, done, info = step_api_compatibility(
    env.step(0), output_truncation_bool=False
)

# Convert to new API (5-tuple)
obs, reward, terminated, truncated, info = step_api_compatibility(
    env.step(0), output_truncation_bool=True
)

# Works with vector environments too
vec_env = gym.make_vec("CartPole-v0", vectorization_mode="sync")
_, _ = vec_env.reset()
obs, rewards, dones, infos = step_api_compatibility(
    vec_env.step([0]), is_vector_env=True, output_truncation_bool=False
)

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime