Environment:Farama Foundation Gymnasium Box2D Physics Backend

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

Overview

Box2D 2D physics engine with pygame-ce rendering for BipedalWalker, CarRacing, and LunarLander environments.

Description

This environment provides the Box2D 2D physics simulation backend required for the Box2D-family Gymnasium environments: BipedalWalker-v3, BipedalWalkerHardcore-v3, CarRacing-v3, LunarLander-v3, and LunarLanderContinuous-v3. Box2D handles rigid body physics simulation while pygame-ce provides the rendering backend. The SWIG build tool is required to compile Box2D Python bindings from C++ source.

Usage

Use this environment when running any Box2D-based Gymnasium environment. Note that unlike other environment families, Box2D environments require pygame even for non-rendering operations (e.g., CarRacing uses pygame for internal surface management during `reset()` and `step()`).

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	All platforms supported
Build Tools	C++ compiler	Required for SWIG compilation of Box2D
Display	Optional	Required only for `human` render mode
Disk	~30MB	Box2D + pygame-ce

Dependencies

System Packages

C++ compiler (gcc/g++ on Linux, Xcode on macOS, MSVC on Windows)

Python Packages

`box2d` == 2.3.10
`pygame-ce` >= 2.1.3
`swig` == 4.*

Credentials

No credentials required.

Quick Install

# SWIG must be installed first for Box2D compilation
pip install swig
pip install "gymnasium[box2d]"

Code Evidence

Box2D import guard from `gymnasium/envs/box2d/lunar_lander.py:14-27`:

try:
    import Box2D
    from Box2D.b2 import (
        circleShape,
        contactListener,
        edgeShape,
        fixtureDef,
        polygonShape,
        revoluteJointDef,
    )
except ImportError as e:
    raise DependencyNotInstalled(
        'Box2D is not installed, you can install it by run `pip install swig` followed by `pip install "gymnasium[box2d]"`'
    ) from e

Pygame requirement in CarRacing from `gymnasium/envs/box2d/car_racing.py:21-29`:

try:
    # As pygame is necessary for using the environment (reset and step) even without a render mode
    #   therefore, pygame is a necessary import for the environment.
    import pygame
    from pygame import gfxdraw
except ImportError as e:
    raise DependencyNotInstalled(
        'pygame is not installed, run `pip install "gymnasium[box2d]"`'
    ) from e

Common Errors

Error Message	Cause	Solution
`DependencyNotInstalled: Box2D is not installed`	Box2D package missing	`pip install swig && pip install "gymnasium[box2d]"`
`error: Failed building wheel for box2d`	SWIG not installed first	Install SWIG before Box2D: `pip install swig`
`DependencyNotInstalled: pygame is not installed`	pygame-ce missing	`pip install "gymnasium[box2d]"`

Compatibility Notes

CarRacing specificity: Pygame is required at import time (not just for rendering) because CarRacing uses pygame surfaces internally during `reset()` and `step()`.
SWIG version: Must use SWIG 4.x series. Other versions may fail to compile Box2D bindings.
box2d-py vs box2d: The `gymnasium[all]` extra installs `box2d-py==2.3.5` while `gymnasium[box2d]` installs `box2d==2.3.10`. Both provide the same `Box2D` Python module.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment