Install & Compatibility
Where this runs
tested against v0.12.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.0s · import 0.431s · 99MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ALEInterface
✓ from ale_py import ALEInterface
✗ from ale_py._ale_py import ALEInterface
The internal _ale_py module should not be directly imported.
roms
✓ from ale_py import roms
✗ import ale_py.roms
While 'import ale_py.roms' works, 'from ale_py import roms' is more direct for accessing ROM paths.
register_envs (Gymnasium)
✓ import gymnasium as gym
import ale_py
gym.register_envs(ale_py)
✗ import gymnasium as gym
env = gym.make('ALE/Breakout-v5')
Gymnasium environments need explicit registration via `ale_py` before `gym.make` can find them.
This quickstart demonstrates both the direct Python interface of ALEInterface to interact with Atari games and its integration with the Gymnasium API. It shows how to load a ROM (now included in the package), reset the game, take an action, and retrieve observations. The Gymnasium example highlights environment registration and interaction.
import gymnasium as gym
import ale_py
from ale_py import ALEInterface, roms
# --- Direct ALEInterface usage ---
ale = ALEInterface()
# ROMs are now packaged within ale-py, access via roms.get_rom_path
ale.loadROM(roms.get_rom_path("breakout"))
ale.reset_game()
reward = ale.act(0) # Perform a 'noop' action
screen_obs = ale.getScreenRGB()
print(f"Direct ALE: Initial reward: {reward}, Screen shape: {screen_obs.shape}")
ale.close()
# --- Gymnasium integration ---
# Register ALE environments with Gymnasium
gym.register_envs(ale_py)
env = gym.make('ALE/Breakout-v5', render_mode='rgb_array')
obs, info = env.reset()
print(f"Gymnasium: Initial observation shape: {obs.shape}")
action = env.action_space.sample() # Take a random action
obs, reward, terminated, truncated, info = env.step(action)
print(f"Gymnasium: Step reward: {reward}, Terminated: {terminated}, Truncated: {truncated}")
env.close()
Debug
Known issues
breakingStarting with ale-py v0.9.0, the library transitioned from supporting OpenAI Gym to Gymnasium (>= 1.0.0a1). The `gym` package is no longer maintained, and `ale-py` uses Gymnasium as the sole backend environment. This requires adapting code that used the older `gym` API.fixMigrate your environment interaction code to use Gymnasium's API. Ensure `gymnasium` is installed (`pip install gymnasium`). Explicitly import `ale_py` and call `gymnasium.register_envs(ale_py)` before creating any Atari environments with `gymnasium.make`.
affects: >=0.9.0
breakingAtari ROMs are now packaged directly within the `ale-py` PyPI installation since v0.9.0, eliminating the need for `pip install "gym[accept-rom-license]"` or the `ale-import-roms` tool for standard ROMs. However, custom or additional ROMs can still be managed via `ale-import-roms` or by setting the `ALE_ROM_DIR` environment variable.fixFor packaged ROMs, use `from ale_py import roms; ale.loadROM(roms.get_rom_path("gamename"))`. If you need custom ROMs, continue using `ale-import-roms /path/to/roms/` or set the `ALE_ROM_DIR` environment variable to your ROM directory. affects: >=0.9.0
deprecatedDirect importing of `atari-py roms` (e.g., `import ale_py.roms as roms` to get external ROMs) will not be supported in future releases of `ale-py` for external ROM handling.fixRely on the ROMs packaged within `ale-py` via `roms.get_rom_path()` or use the `ale-import-roms` command-line tool/`ALE_ROM_DIR` environment variable for managing custom ROMs. The `roms` module itself is still correct for accessing *internal* ROM paths.
affects: >=0.9.0
gotchaOlder versions of `ale-py` might not have wheels available for the latest Python versions (e.g., Python 3.12 prior to `ale-py` v0.9.0). This can lead to installation failures.fixEnsure you are using `ale-py` version 0.9.0 or newer for Python 3.12+ compatibility, or use an earlier Python version (e.g., 3.11) with older `ale-py` versions. Always ensure `pip` is up-to-date (`pip install --upgrade pip`).
affects: <0.9.0 with Python >=3.12
gotchaWhen using Gymnasium environments, the `env.render()` method is generally discouraged in favor of supplying the `render_mode` keyword argument during environment initialization for improved rendering capabilities (frame-perfect, audio, scaling).fixInitialize your Gymnasium environment with `render_mode='human'` or `render_mode='rgb_array'` (e.g., `env = gym.make('ALE/Breakout-v5', render_mode='rgb_array')`). affects: All versions with Gymnasium
Errors
Common errors & fixes
No module named 'ale_py._ale_py' (or similar ModuleNotFoundError when importing gym)
This often occurs when `ale-py`'s internal C++ bindings are not correctly compiled or located, or when Gymnasium environments are used without properly registering `ale_py`.
fixEnsure `ale-py` is installed correctly, possibly in a fresh virtual environment. For Gymnasium, you *must* explicitly `import ale_py` and then call `gymnasium.register_envs(ale_py)` before creating any Atari environments with `gym.make()`.
ERROR: Could not find a version that satisfies the requirement ale-py (from versions: none) / ERROR: No matching distribution found for ale-py
This error typically indicates that your Python version is not supported by the available `ale-py` wheels on PyPI, or your `pip` is outdated.
fixUpgrade `pip` (`pip install --upgrade pip`). If the error persists, check `ale-py`'s PyPI page for supported Python versions and consider using a compatible Python version (e.g., Python 3.9-3.11 for older `ale-py`, or `ale-py` >=0.9.0 for Python 3.12+).
game_env = gym.make('Pong-v4') fails with a ROM error or environment not found
Older `gym` versions required manual ROM installation or `gym[atari,accept-rom-license]`. With Gymnasium, the environment registration is often missed, or a very old `ale-py` is used that doesn't include ROMs.
fixEnsure you are using `gymnasium` and `ale-py >=0.9.0`. Explicitly import `ale_py` and then call `gymnasium.register_envs(ale_py)` *before* `gym.make()`. If using `pip install "gymnasium[atari]"`, ROMs should be automatically handled. If you need custom ROMs, use `ale-import-roms /path/to/roms` or set `ALE_ROM_DIR`.
Upgrade
Version history
0.12.0latest on PyPI · released May 30, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
gymnasiumoptionalRequired for modern OpenAI Gym API (Gymnasium) integration and Atari environments.