How to Fix Common Gymnasium Setup Problems
Fix the most common Gymnasium installation and environment errors, including old Gym tutorials, missing extras, rendering dependencies, and Python version issues.
Old tutorials use gym
One of the first things you will run into is code that says:
import gym
while your installation uses:
import gymnasium as gym
Gymnasium is the maintained fork of OpenAI Gym, and its API differs from older Gym releases. In particular, modern Gymnasium uses terminated and truncated in place of the old single done value.
If you are following an old tutorial, do not downgrade everything to make it work. Change the import to Gymnasium and change the step unpacking to the five values in the done section below.
An environment cannot be found
A missing environment is usually one of three things: the wrong ID, a missing extra, or a package that was never imported.
First, list what is actually registered in your install:
import gymnasium as gym
gym.pprint_registry()
IDs are exact. Case and version matter. CartPole-v1 is registered. CartPole on its own is not, and CartPole-v0 is not a current Gymnasium ID.
Second, a base install does not include every environment family. Installing Gymnasium alone gives you the core library, not the physics, rendering, or Atari dependencies. Install the extra for the family you are using:
pip install "gymnasium[classic-control]"
pip install "gymnasium[toy-text]"
pip install "gymnasium[mujoco]"
pip install "gymnasium[atari]"
pip install "gymnasium[accept-rom-license]"
The family for each common environment:
- Classic control,
CartPole-v1,Acrobot-v1,MountainCar-v0,MountainCarContinuous-v0,Pendulum-v1:gymnasium[classic-control] - Toy text,
FrozenLake-v1,Taxi-v3,Blackjack-v1,CliffWalking-v0:gymnasium[toy-text] - MuJoCo,
Ant-v5,HalfCheetah-v5,Hopper-v5,Humanoid-v5,Walker2d-v5,Swimmer-v5:gymnasium[mujoco] - Atari,
ALE/Breakout-v5and otherALE/games:gymnasium[atari], plusgymnasium[accept-rom-license]for the ROMs - Box2D,
LunarLander-v3,BipedalWalker-v3,CarRacing-v3: see the Box2D section below
If the ID is in the registry but the extra is missing, the error at make time is a missing dependency, not a registration error. If the ID is not in the registry at all, the ID itself is wrong, or it comes from a third-party package you have not imported yet. A third-party environment is only registered after its package is imported, so import that package before calling gym.make().
Old Atari IDs are a common version of this. Breakout-v0 is not a Gymnasium ID. The current form is ALE/Breakout-v5.
Box2D installation errors
Box2D is a particularly common source of installation problems because it has native components.
For current Gymnasium releases, the installation is:
pip install swig
pip install "gymnasium[box2d]"
SWIG is required when Box2D has to be built from source. On Python 3.13 or below, Gymnasium uses a prebuilt pybox2d wheel. On Python 3.14 or above, there is no prebuilt pybox2d wheel, so the box2d extra builds box2d from source and SWIG is required. On Windows, a source build also needs a C++ compiler, which means the Visual C++ Build Tools.
Gymnasium 1.3.0 replaced pygame with pygame-ce for Box2D and classic control rendering, and that replacement is what unlocks Python 3.14 compatibility. Do not install plain pygame to fix a Box2D or classic control rendering error. Installing the family extra pulls in pygame-ce.
Rendering errors
A basic environment can work perfectly while rendering fails. That is because rendering often requires additional packages that are not necessary for simply stepping through an environment.
Test the split first. Create the environment with no render mode and step it:
import gymnasium as gym
env = gym.make("CartPole-v1")
observation, info = env.reset()
env.step(env.action_space.sample())
env.close()
If that works, the environment and its physics dependency are fine, and the problem is rendering only.
Set the render mode when you create the environment, not when you call render:
env = gym.make("CartPole-v1", render_mode="human")
env = gym.make("CartPole-v1", render_mode="rgb_array")
Calling env.render() on an environment created with no render mode does not turn rendering on.
Rendering for each family:
- Classic control,
CartPole-v1and the other classic control environments:pip install "gymnasium[classic-control]" - Toy text,
FrozenLake-v1,Taxi-v3, and the other toy text environments:pip install "gymnasium[toy-text]" - Box2D,
LunarLander-v3,BipedalWalker-v3,CarRacing-v3:pip install "gymnasium[box2d]" - MuJoCo,
Ant-v5and the other MuJoCo environments:pip install "gymnasium[mujoco]"
render_mode="human" needs a display. On a headless server, over SSH, or in a container with no display, human will fail even when the rendering dependency is installed. Use render_mode="rgb_array" there, which returns frames as NumPy arrays with no window. If you do need a window on a headless Linux machine, run the script under a virtual display:
xvfb-run -s "-screen 0 1400x900x24" python your_script.py
done is not working
If you copied an old RL tutorial, you may have code like:
observation, reward, done, info = env.step(action)
Modern Gymnasium returns:
observation, reward, terminated, truncated, info = env.step(action)
The usual episode-ending check is:
if terminated or truncated:
observation, info = env.reset()
This is an API difference rather than an installation problem. An environment reaching its terminal state is different from an episode being stopped by a time limit. terminated is the first case. truncated is the second, for example a 500-step limit on CartPole-v1.
Python version problems
Check your version before changing dependencies:
python --version
Gymnasium 1.3 is tested on Python 3.10 through 3.14. Below 3.10, upgrade Python. On 3.14, the Box2D case above is the one to watch: Box2D builds from source there, so SWIG is required, and a plain pip install "gymnasium[box2d]" without SWIG will fail at build time.
Do not fix a version problem by installing packages into the system Python and then running the script with a different Python. Create one virtual environment, install everything in it, and run from it:
python -m venv .venv
source .venv/bin/activate
pip install "gymnasium[classic-control]"
You are mixing environments
A surprisingly common problem is installing Gymnasium into one Python environment and running the script with another.
Check which Python you are actually using:
python -c "import sys; print(sys.executable)"
Then check Gymnasium itself:
python -c "import gymnasium; print(gymnasium.__version__)"
If those commands work in your terminal but not in your IDE, the IDE is using a different interpreter. Point the IDE at the same interpreter that printed sys.executable above, and reinstall the extras into that environment if the IDE environment is a different one.
Isolate the failing layer
Run these three tests in order, and stop at the first one that fails:
import gymnasium as gym
print(gymnasium.__version__)
env = gym.make("CartPole-v1")
observation, info = env.reset()
env.step(env.action_space.sample())
env.close()
env = gym.make("CartPole-v1", render_mode="rgb_array")
observation, info = env.reset()
frame = env.render()
env.close()
The first test failing means the install or interpreter is wrong. The second test failing means the environment or its family extra is wrong. The third test failing means rendering is wrong. Fix only the layer that failed, and do not reinstall everything.
For the initial installation and a basic working example, see How to Set Up OpenAI Gymnasium.
Comments
One comment per thread every 30 minutes · edits are unlimited.