---

name: vectorization description: "Create, step, wrap, and troubleshoot Gymnasium vectorized environments for batched training and evaluation." disable-model-invocation: true metadata: disco-role: operating license: MIT

Gymnasium Vectorization

Use this sub-skill when a task needs multiple Gymnasium environments stepped as one batch: gymnasium.make_vec, SyncVectorEnv, AsyncVectorEnv, vector wrappers, batched observations/actions/rewards/masks/infos, autoreset modes, or vector multiprocessing troubleshooting.

Start Here

1. Prefer gymnasium.make_vec(env_id, num_envs=..., vectorization_mode="sync" | "async") for registered environments.
2. Use envs.action_space.sample() or another action batch matching envs.action_space; use envs.single_action_space only to reason about one sub-environment.
3. Treat rewards, terminations, and truncations as arrays of shape (num_envs,), not scalar booleans.
4. Check envs.metadata["autoreset_mode"] before interpreting post-terminal observations or writing bootstrapping logic.
5. Use gymnasium.wrappers.vector wrappers around vector envs; pass single-env wrappers through make_vec(..., wrappers=[...]) only when they should wrap each sub-environment before vectorization.
6. Always call envs.close(), especially for AsyncVectorEnv worker processes.

Route by Task

Task	Read
Create or step vector envs, choose sync vs async, handle batched outputs	references/vector-envs.md
Apply vector wrappers, transform batched spaces, use vector space utilities	references/vector-wrappers-and-spaces.md
Debug actions, masks, autoreset, multiprocessing, shared memory, render/video	references/troubleshooting.md
Prove a small local vector loop works	scripts/vector_env_smoke.py

Minimum Correct Pattern

import gymnasium as gym

envs = gym.make_vec("CartPole-v1", num_envs=4, vectorization_mode="sync")
try:
    observations, infos = envs.reset(seed=123)
    actions = envs.action_space.sample()
    observations, rewards, terminations, truncations, infos = envs.step(actions)
    done_mask = terminations | truncations
finally:
    envs.close()

For a quick sanity check from this sub-skill directory, run python scripts/vector_env_smoke.py --help and then python scripts/vector_env_smoke.py --mode sync --num-envs 2 --steps 4.

Scope Boundaries

• Use ../environment-api/SKILL.md for single Env contracts, custom environment classes, registration, check_env, and non-vector reset/step migration.
• Use ../spaces-data/SKILL.md for fundamental Space constructors, dtype/shape design, contains, flattening, and JSONable conversion.
• Use ../wrappers-recording/SKILL.md for single-environment wrappers, recording, rendering, and custom wrapper subclassing depth.
• Use ../builtin-envs/SKILL.md for built-in family selection, optional extras/backends, Atari/ALE, Box2D, MuJoCo, and Toy Text action masks.

Keep runtime guidance self-contained. Do not depend on the Gymnasium source tree, tests, or documentation paths at runtime.