Environment:Farama Foundation Gymnasium Video Recording Dependencies

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

Overview

MoviePy and OpenCV dependencies required for recording environment episodes as video files and processing image observations.

Description

This environment provides the optional visualization and media processing dependencies used by Gymnasium's video recording and image processing features. MoviePy is required by `save_video()` and the `RecordVideo` wrapper for encoding frames into MP4 video files. OpenCV (`cv2`) is required by the `ResizeObservation` wrapper and `AtariPreprocessing` wrapper for image resizing and grayscale conversion. Matplotlib is optionally used by the `play()` utility for real-time plotting during interactive play sessions.

Usage

Use this environment when recording agent behavior as video, preprocessing Atari image observations, or using interactive play with plotting. Specifically required for the `RecordVideo` wrapper, `save_video()` utility, `ResizeObservation` wrapper, and `AtariPreprocessing` wrapper.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	All platforms supported
Display	Optional	Tk backend needed for matplotlib interactive plots
Disk	~100MB	MoviePy + OpenCV + matplotlib

Dependencies

Python Packages

`moviepy` >= 1.0.0
`opencv-python` >= 3.0
`matplotlib` >= 3.0
`seaborn` >= 0.13

Credentials

No credentials required.

Quick Install

# Install all visualization/media dependencies
pip install "gymnasium[other]"

# Or install individually
pip install moviepy>=1.0.0 opencv-python>=3.0 matplotlib>=3.0

Code Evidence

MoviePy import guard from `gymnasium/utils/save_video.py:11-16`:

try:
    from moviepy.video.io.ImageSequenceClip import ImageSequenceClip
except ImportError as e:
    raise gym.error.DependencyNotInstalled(
        'moviepy is not installed, run `pip install "gymnasium[other]"`'
    ) from e

OpenCV import guard from `gymnasium/wrappers/transform_observation.py:381-386`:

try:
    import cv2
except ImportError as e:
    raise DependencyNotInstalled(
        'opencv (cv2) is not installed, run `pip install "gymnasium[other]"`'
    ) from e

OpenCV in AtariPreprocessing from `gymnasium/wrappers/atari_preprocessing.py:95-100`:

try:
    import cv2  # noqa: F401
except ImportError as e:
    raise gym.error.DependencyNotInstalled(
        'opencv-python package not installed, run `pip install "gymnasium[other]"` to get dependencies for atari'
    ) from e

Matplotlib soft import in play utility from `gymnasium/utils/play.py:29-36`:

try:
    import matplotlib
    matplotlib.use("TkAgg")
    import matplotlib.pyplot as plt
except ImportError:
    logger.warn('matplotlib is not installed, run `pip install "gymnasium[other]"`')
    matplotlib, plt = None, None

Common Errors

Error Message	Cause	Solution
`DependencyNotInstalled: moviepy is not installed`	moviepy missing	`pip install "gymnasium[other]"`
`DependencyNotInstalled: opencv (cv2) is not installed`	opencv-python missing	`pip install "gymnasium[other]"`
`DependencyNotInstalled: matplotlib is not installed`	matplotlib missing (in PlayPlot)	`pip install "gymnasium[other]"`
`TclError: no display name and no $DISPLAY environment variable`	matplotlib TkAgg backend on headless server	Use `matplotlib.use("Agg")` or set `DISPLAY`

Compatibility Notes

Matplotlib soft import: In `play.py`, matplotlib is imported with a soft fallback (warns instead of raising). The `PlayPlot` class raises `DependencyNotInstalled` only when actually instantiated.
AtariPreprocessing: Requires opencv-python specifically; other OpenCV builds (e.g., opencv-python-headless) also work.
scale_obs warning: Using `AtariPreprocessing` with `scale_obs=True` limits the memory optimization benefits of `FrameStackObservation` wrapper, as observations become float32 instead of uint8.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment