Implementation:Farama Foundation Gymnasium Box Discrete Dict Spaces

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

Overview

Concrete tools for defining observation and action space structure provided by the Gymnasium spaces module.

Description

The Gymnasium spaces module provides the three most commonly used space types for defining environment interfaces:

Box(low, high, shape, dtype): An n-dimensional continuous space bounded by per-element low/high values. Used for physical states (positions, velocities) and image observations.
Discrete(n, start, dtype): A finite integer space {start, ..., start+n-1}. Used for categorical actions.
Dict(spaces): A dictionary of named sub-spaces for structured observations containing heterogeneous components.

Usage

Use these classes in custom environment __init__ methods to define self.observation_space and self.action_space. Box is used for continuous control environments, Discrete for tabular/grid environments, and Dict for environments with multiple observation components.

Code Reference

Source Location

Repository: Gymnasium
File (Box): gymnasium/spaces/box.py, Lines L37-475
File (Discrete): gymnasium/spaces/discrete.py, Lines L15-217
File (Dict): gymnasium/spaces/dict.py, Lines L16-262

Signature

class Box(Space[NDArray[Any]]):
    def __init__(
        self,
        low: SupportsFloat | NDArray[Any],
        high: SupportsFloat | NDArray[Any],
        shape: Sequence[int] | None = None,
        dtype: type = np.float32,
        seed: int | np.random.Generator | None = None,
    ):
        """An n-dimensional bounded continuous space.

        Args:
            low: Lower bounds of each dimension.
            high: Upper bounds of each dimension.
            shape: Shape of the space (inferred from low/high if None).
            dtype: Data type of elements.
            seed: Optional RNG seed.
        """

class Discrete(Space[IntType]):
    def __init__(
        self,
        n: int | np.integer[Any],
        seed: int | np.random.Generator | None = None,
        start: int | np.integer[Any] = 0,
        dtype: str | type[np.integer[Any]] = np.int64,
    ):
        """A finite set of integers {start, ..., start+n-1}."""

class Dict(Space[dict[str, Any]]):
    def __init__(
        self,
        spaces: dict[str, Space] | None = None,
        seed: int | dict | np.random.Generator | None = None,
        **spaces_kwargs: Space,
    ):
        """A dictionary of named sub-spaces."""

Import

from gymnasium.spaces import Box, Discrete, Dict

I/O Contract

Inputs

Name	Type	Required	Description
Box: low, high	float or ndarray	Yes	Bounds for each dimension
Box: shape	tuple[int] or None	No	Space dimensionality (inferred from low/high)
Discrete: n	int	Yes	Number of elements
Dict: spaces	dict[str, Space]	Yes	Mapping of named sub-spaces

Outputs

Name	Type	Description
sample()	ndarray / int / dict	Random sample from the space
contains(x)	bool	Membership test
shape	tuple	Shape of the space

Usage Examples

Custom Environment Spaces

import numpy as np
from gymnasium.spaces import Box, Discrete, Dict

# Continuous observation space: 4D state vector
observation_space = Box(
    low=np.array([-4.8, -np.inf, -0.418, -np.inf]),
    high=np.array([4.8, np.inf, 0.418, np.inf]),
    dtype=np.float32,
)

# Discrete action space: 2 actions (left, right)
action_space = Discrete(2)

# Structured observation with Dict
dict_obs_space = Dict({
    "position": Box(low=-1.0, high=1.0, shape=(2,)),
    "velocity": Box(low=-5.0, high=5.0, shape=(2,)),
    "target": Discrete(4),
})

# Sampling
print(observation_space.sample())  # array of shape (4,)
print(action_space.sample())       # integer 0 or 1
print(dict_obs_space.sample())     # {"position": ..., "velocity": ..., "target": ...}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment