Heuristic:Farama Foundation Gymnasium Render Mode Selection Guide
| Knowledge Sources | |
|---|---|
| Domains | Reinforcement_Learning, Visualization |
| Last Updated | 2026-02-15 03:00 GMT |
Overview
Guide for selecting the correct `render_mode` parameter: use `None` for training, `"rgb_array"` for video recording, and `"human"` for interactive debugging.
Description
Gymnasium environments accept a `render_mode` parameter at construction time (not changeable after initialization). The render mode determines how visual output is generated and returned. Choosing the wrong mode leads to common errors: `None` mode silently produces no output, `"human"` mode blocks on display updates, and `"rgb_array"` mode without proper wrapper setup produces no video files. Additionally, rendering objects should be initialized in `__init__` (not in `render()`) since the render mode is known at construction time.
Usage
Use this heuristic when creating environments via `gymnasium.make()` and deciding whether/how to render, when recording training videos, or when debugging environment behavior visually.
The Insight (Rule of Thumb)
- For training (no rendering): Use `render_mode=None` (default). No rendering overhead.
- For video recording: Use `render_mode="rgb_array"` and wrap with `RecordVideo`. Frames are returned as numpy arrays (shape: H x W x 3, dtype: uint8).
- For interactive debugging: Use `render_mode="human"`. Rendering happens automatically during `step()`.
- For frame collection: Use `render_mode="rgb_array_list"` or `render_mode="ansi_list"` (auto-applied by `gymnasium.make()` via the `RenderCollection` wrapper).
- Trade-off: Each non-None render mode adds overhead. `"human"` mode significantly slows training due to display synchronization.
- Implementation note: Initialize rendering resources in `__init__`, not in `render()`.
Reasoning
The render mode is immutable after construction because rendering backends (pygame windows, OpenGL contexts, offscreen buffers) must be allocated at initialization time. Attempting to switch modes at runtime would require tearing down and rebuilding these resources, which is error-prone and expensive.
The `passive_env_checker` validates render output types per mode: `"human"` must return `None`, `"rgb_array"` must return a uint8 numpy array with shape (x, y, 3), and `"ansi"` must return a string. Missing `render_fps` in metadata causes inconsistent rendering frame rates.
Code Evidence
Render mode conventions from `gymnasium/core.py:169-180`:
# By convention, if the render_mode is:
# - None (default): no render is computed.
# - "human": continuously rendered in the current display, for human consumption.
# Returns None.
# - "rgb_array": Return a single frame as np.ndarray with shape (x, y, 3).
# - "ansi": Return a string or StringIO.
# - "rgb_array_list" and "ansi_list": List versions via RenderCollection wrapper.
Initialization guidance from `gymnasium/core.py:165-167`:
# As the render_mode is known during __init__, the objects used to render
# the environment state should be initialised in __init__.
Render validation from `gymnasium/utils/passive_env_checker.py:260-310`:
# "human" render_mode should return None
# "rgb_array" should be numpy array, dtype uint8, shape (x, y, 3)
# "depth_array" should be numpy array with 2 axes
# "ansi"/"ascii" should return string
Missing render_fps warning from `gymnasium/utils/passive_env_checker.py:333-335`:
# No render_fps declared can cause inconsistent rendering fps