Environment:ARISE Initiative Robosuite MuJoCo Python

Knowledge Sources	robosuite MuJoCo Python Bindings
Domains	Robotics_Simulation, Infrastructure
Last Updated	2026-02-15 07:00 GMT

Overview

Python 3+ environment with MuJoCo >= 3.3.0, NumPy, SciPy, and the core robosuite simulation stack for robot manipulation research.

Description

This environment provides the foundational runtime for all robosuite simulation workflows. It is built around the modern mujoco Python bindings (>= 3.3.0), replacing the legacy mujoco-py package. The codebase includes a compatibility layer (binding_utils.py) that wraps the new mujoco API to provide mujoco-py-like interfaces (MjSim, MjModel, MjData, MjSimState). Additional core dependencies include NumPy for array operations, SciPy for scientific computing, Numba for JIT-compiled performance-critical functions, and mink for whole-body inverse kinematics.

Usage

Use this environment for all robosuite workflows: environment setup and simulation, teleoperation, human demonstration collection, Gymnasium RL integration, and domain randomization training. Every Implementation page in this wiki requires this environment as a prerequisite.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Linux recommended; Windows requires mujoco.dll loading
Python	>= 3.0	Python 3.10+ recommended
Hardware	CPU (minimum)	GPU optional for rendering (see GPU_Rendering environment)

Dependencies

System Packages

`mujoco` >= 3.3.0 (MuJoCo physics engine with Python bindings)

Python Packages

`numpy` >= 1.13.3
`numba` >= 0.49.1
`scipy` >= 1.2.3
`mujoco` >= 3.3.0
`mink` == 0.0.5
`qpsolvers[quadprog]` >= 4.3.1
`Pillow`
`opencv-python`
`pynput`
`termcolor`
`pytest`
`tqdm`

Optional Packages

`gymnasium` (required for GymWrapper)
`hidapi` (macOS only, required for SpaceMouse)
`h5py` (required for demonstration HDF5 utilities)
`robosuite-models` == 1.0.0 (extra robot models)
`usd-core` (USD export and rendering)

Credentials

No credentials are required for core robosuite functionality.

The following optional environment variables affect rendering behavior:

`MUJOCO_GL`: Rendering backend selection (`egl`, `osmesa`, `glx`, `cgl`, `wgl`)
`CUDA_VISIBLE_DEVICES`: GPU device selection for EGL rendering
`MUJOCO_EGL_DEVICE_ID`: Specific EGL device ID (must be within CUDA_VISIBLE_DEVICES)
`PYOPENGL_PLATFORM`: Must be `egl` or unset when using EGL context

Quick Install

# Install robosuite with all core dependencies
pip install robosuite

# Or install from source
git clone https://github.com/ARISE-Initiative/robosuite.git
cd robosuite
pip install -e .

# Install optional extras
pip install gymnasium hidapi h5py robosuite-models==1.0.0 usd-core

Code Evidence

MuJoCo version requirement from `setup.py:21`:

install_requires=[
    "numpy>=1.13.3",
    "numba>=0.49.1",
    "scipy>=1.2.3",
    "mujoco>=3.3.0",
    "mink==0.0.5",
    "qpsolvers[quadprog]>=4.3.1",
    ...
]

MuJoCo binding compatibility layer from `robosuite/utils/binding_utils.py:12-14`:

import mujoco
import numpy as np
_MjSim_render_lock = Lock()

Platform-specific DLL loading from `robosuite/utils/binding_utils.py:26-27`:

_SYSTEM = platform.system()
if _SYSTEM == "Windows":
    ctypes.WinDLL(os.path.join(os.path.dirname(mujoco.__file__), "mujoco.dll"))

Optional dependency handling from `robosuite/__init__.py:27-33`:

try:
    import robosuite_models
except:
    ROBOSUITE_DEFAULT_LOGGER.warning(
        "Could not import robosuite_models. Some robots may not be available."
    )

Common Errors

Error Message	Cause	Solution
`Could not import robosuite_models`	robosuite-models package not installed	`pip install robosuite-models==1.0.0`
`Could not load the mink-based whole-body IK`	mink or dependencies not properly installed	Reinstall mink: `pip install mink==0.0.5 qpsolvers[quadprog]>=4.3.1`
`No private macro file found!`	macros_private.py not created	Run `python robosuite/scripts/setup_macros.py` to create private macros file
`ModuleNotFoundError: hid`	hidapi not installed (needed for SpaceMouse)	`pip install hidapi` (macOS only)
`Environment X not found`	Unregistered environment name passed to `make()`	Check `robosuite.ALL_ENVIRONMENTS` for valid names

Compatibility Notes

Windows: Requires explicit loading of `mujoco.dll` via ctypes. Rendering backend set to `wgl`.
macOS: Rendering backend set to `cgl`. SpaceMouse requires `hidapi` package.
Linux: Default rendering backend is `egl` (GPU) or `osmesa` (software). See GPU_Rendering environment for GPU-specific requirements.
mujoco-py migration: The codebase uses a compatibility wrapper (`binding_utils.py`) that provides mujoco-py-like API (MjSim, MjModel, MjData) on top of the modern `mujoco` package. Direct mujoco-py is not supported.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment