dmlab-gym

A Gymnasium port of DeepMind Lab — 44 first-person 3D environments for Reinforcement Learning research, updated for Bazel 8 and Python 3.13.

[Original Paper]

What is this?

This project wraps the original DeepMind Lab C engine (Quake 3 based) as standard Gymnasium environments.

The C game code remains unchanged with deprecation warnings removed. This package only adds a Python interface layer around it.

Key features

• Standard gym.make() API for all 44 levels
• Compatible with all standard Gymnasium wrappers
• Vectorized environments via gym.make_vec()
• Python 3.13+ support
• Managed with uv and pyproject.toml

Installation

pip install dmlab-gym

Requirements: Python 3.13+ (64-bit), Linux x86_64.

Prerequisites

• uv (Python environment management)
• Podman or Docker (container builds)
• OSMesa (runtime dependency for headless rendering) — installed automatically by dmlab-gym build if missing

Building the Native Extension

After installing, build the DeepMind Lab native extension:

dmlab-gym build                        # build and install deepmind-lab
dmlab-gym build -o ~/my_output         # custom output directory
dmlab-gym build --no-install           # build only, skip install

This auto-detects Podman or Docker, builds the native extension inside a container, installs the wheel, and verifies the import automatically.

$ dmlab-gym build

Building deepmind-lab (podman)
  Source: /home/user/.local/share/dmlab-gym/source
  Output: /home/user/my-project/lab

  ✓ Building container image
  ✓ Compiling native extension (this may take a while)
  ✓ Installing wheel
  ✓ deepmind_lab is importable

  Done! deepmind-lab installed from deepmind_lab-1.0-py3-none-any.whl

Quick Start

Single environment (standard Gymnasium API)

import gymnasium as gym
import dmlab_gym  # auto-registers all 44 levels

env = gym.make("dmlab_gym/lt_chasm-v0")
obs, info = env.reset()

for _ in range(1000):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()

env.close()

Vectorized environments (parallel training)

DMLab's C engine only supports one instance per process. Use gym.make_vec to run N copies in separate subprocesses — each gets its own memory-isolated process and stays alive between steps:

import gymnasium as gym
import dmlab_gym

vec_env = gym.make_vec(
    "dmlab_gym/lt_chasm-v0",
    num_envs=8,
    vectorization_mode="async",
)

obs, infos = vec_env.reset()
obs, rewards, terminated, truncated, infos = vec_env.step(vec_env.action_space.sample())
vec_env.close()

To customise environment options (resolution, renderer, etc.), use dmlab_gym.register() to re-register with different settings.

Environments

All environments produce (H, W, 3) RGB observations and use a 7D integer action space Box(shape=(7,), dtype=np.intc). See docs/environments/ for detailed per-group documentation.

Access level lists via dmlab_gym.CORE_LEVELS, dmlab_gym.DMLAB30_LEVELS, or dmlab_gym.ALL_LEVELS.

Environment Options

All options can be passed as keyword arguments to dmlab_gym.register() or directly to DmLabEnv:

Wrappers

One custom wrapper included:

from dmlab_gym.wrappers import ActionDiscretize

env = ActionDiscretize(gym.make("dmlab_gym/lt_chasm-v0", renderer="software"))
env.action_space  # Discrete(9)

Gymnasium Wrapper Compatibility

All standard Gymnasium wrappers are compatible:

License

This project is a derivative work of DeepMind Lab and is distributed under the same licenses:

• GPLv2 -- engine/, q3map2/, assets_oa/
• CC BY 4.0 -- assets/
• Custom academic license -- engine/code/tools/lcc/
• BSD 3-Clause -- q3map2/libs/{ddslib,picomodel}

See LICENSE for full details.

Attribution

Based on DeepMind Lab by DeepMind.