robosuite: MuJoCo Robot Learning Framework, Install and First Run

robosuite is an open-source simulation framework for robot learning, built on the MuJoCo physics engine and designed to give researchers benchmark manipulation environments that others can reproduce. You install it with pip install robosuite, create an environment with suite.make(...), and step it with env.step(action), which returns an observation dictionary, a reward, a done flag and an info dictionary. This guide puts the install, first run, observation and reward reading, and citation steps in one sequence, following the official documentation as read on 2026-11-12.

What robosuite is used for in research

The robosuite overview describes the project as a simulation framework powered by MuJoCo for robot learning, with a set of benchmark environments meant to support reproducible research. It was started in late 2017 by the Stanford Vision and Learning Lab, is maintained with the UT Robot Perception and Learning Lab and NVIDIA GEAR, and is part of the ARISE Initiative. The documentation lists version 1.5 as the current line, adding humanoid robots, composite and whole-body controllers, more teleoperation devices, and photorealistic rendering including an Isaac Sim renderer.

The framework is organised into components named in the documentation: robots, objects, environments, sensors, I/O devices (keyboard, SpaceMouse, DualSense, and drag-and-drop in the MuJoCo viewer), renderers and controllers (joint velocity, inverse kinematics, operational space and whole-body). It also includes tools for collecting, replaying and learning from human demonstrations, which is why it is commonly met in imitation learning work. For the wider field, see the CASRAI overview of robot learning.

The task environments documented for v1.5 are, for a single arm, block lifting, block stacking, pick-and-place, nut assembly, door opening and table wiping, and, for two arms, two-arm lifting, peg-in-hole and handover. The short names used in code include Lift, Stack and Door; example robots in the basic-usage page are Panda, Sawyer and Jaco.

Install or access (official source only)

The installation page describes Python 3 on macOS or Linux (its Conda example uses Python 3.10) and lists mujoco and numpy as requirements, without pinning versions. It recommends a virtual environment or Conda environment so that the simulator dependencies stay isolated from other projects.

Route	Commands from the installation page	Use when
From PyPI	pip install robosuite	You want the released package and do not plan to edit the framework.
From source (editable)	git clone https://github.com/ARISE-Initiative/robosuite.git, then cd robosuite, then pip3 install -r requirements.txt	You want to read or modify the code, or use the demo scripts directly from the repository.
Optional extras	pip3 install -r requirements-extra.txt	You need the Gym interfaces, PyBullet inverse kinematics, or SpaceMouse and DualSense devices.

The source code is hosted in the ARISE-Initiative GitHub organisation. Since v1.4, robosuite uses the official DeepMind MuJoCo Python binding. The v1.5 release is dated 28 October 2024 on the repository.

Check that the install works

After a pip install, run python -m robosuite.demos.demo_random_action. After a source install, run python robosuite/demos/demo_random_action.py. Both open a simulated robot driven by random actions. On macOS the documentation says to use mjpython in place of python for the default mjviewer renderer.

Step-by-step: create an environment and take your first steps

The basic-usage page builds the first run from the following code. Read your installed version’s documentation before copying it, because the return signature of env.step is documented there as a four-element tuple and releases can change this.

1. Import the libraries: import numpy as np and import robosuite as suite.
2. Create the environment: env = suite.make(env_name="Lift", robots="Panda", has_renderer=True, has_offscreen_renderer=False, use_camera_obs=False). This selects the block-lifting task with a Panda arm, an on-screen viewer, no off-screen rendering and no camera observations.
3. Reset it: env.reset().
4. Loop over steps. Build an action the size of the action specification, for example action = np.random.randn(*env.action_spec[0].shape) * 0.1, then call obs, reward, done, info = env.step(action) and env.render().

Other make arguments named in the environments documentation include gripper_types, controller_configs, env_configuration ("opposed" or "parallel" for two-arm tasks), render_camera, control_freq, horizon, use_object_obs, camera_names, camera_heights, camera_widths, reward_shaping and placement_initializer. In v1.5 the controller setup goes through load_composite_controller_config(controller=...), with "BASIC" (operational space control for arms, joint velocity for the base, joint position for other parts) and "WHOLE_BODY_IK" as the documented options.

Output and how to read it

Each call to env.step returns four things. The observation is an ordered dictionary mapping names to NumPy arrays, the reward is the immediate reward for that step, done is a boolean, and info is a dictionary of extra information. The data table below lists the observation keys and reward modes described in the v1.5 environments page.

Three points are easy to miss. First, the documentation states that episodes do not end when the task succeeds: they run for horizon steps, so a success is read from the reward or success check, not from done. Second, the sparse reward is a binary success signal computed by the environment’s _check_success, while the dense reward is shaped around stages such as reaching, grasping and lifting; a reward_scale setting scales either. Third, images follow the OpenGL convention by default, which means they arrive vertically flipped; a macro called IMAGE_CONVENTION switches to the OpenCV convention.

Choosing a controller and input device

The documentation lists four controller families: joint velocity, inverse kinematics, operational space and whole-body. Operational space control is what the "BASIC" composite configuration uses for arms, so a first run needs no controller configuration at all. When you collect human demonstrations rather than scripted actions, the documented input devices are the keyboard, a SpaceMouse, a DualSense controller, and drag-and-drop with the mouse in the MuJoCo viewer. Devices other than the keyboard and viewer need the extras installed earlier. Recorded demonstrations can be replayed and used for learning with the tools bundled in the framework, which is the workflow that connects robosuite to demonstration-based methods.

Troubleshooting

Symptom	Cause named in the documentation	What to do
The viewer does not open on macOS with python	The default mjviewer renderer needs the MuJoCo launcher on macOS.	Run the script with mjpython.
Import errors for Gym, PyBullet or input devices	These integrations are in the extras file, not the base requirements.	Run pip3 install -r requirements-extra.txt.
Camera images look upside down	The default image convention is OpenGL.	Set the IMAGE_CONVENTION macro to OpenCV, or flip the array.
Code from a tutorial fails on env.step	Tutorials and release documentation can describe different versions.	Check the version you installed against the documentation for that version.
The episode never ends after the task is solved	Episodes run for horizon steps and do not stop on success.	Track success separately and set horizon to the length you need.

Citing robosuite and recording the version

The repository gives the BibTeX key robosuite2020 for the paper “robosuite: A Modular Simulation Framework and Benchmark for Robot Learning” (Zhu, Wong, Mandlekar, Martin-Martin, Joshi, Lin, Maddukuri, Nasiriany and Zhu), arXiv:2009.12293. The arXiv listing shows version 1 on 25 September 2020, version 2 on 15 November 2022 and version 3 on 18 January 2025; version 3 is the one that covers the v1.5 modules and benchmarks. For reproducibility, report the installed robosuite release number, the MuJoCo version, the controller configuration and the horizon and reward settings used, since all of these change results.

Free alternatives and related tools

Tool	What its own page says	Source
robomimic	“A framework for robot learning from demonstration”, offering demonstration datasets collected on robot manipulation tasks and learning algorithms that train on them. It belongs to the ARISE Initiative, as robosuite does.	robomimic.github.io
Isaac Lab	“A GPU-accelerated, open-source framework designed to unify and simplify robotics research workflows”; listed backends are Newton, OVRTX, OVPhysX and NVIDIA Isaac Sim; the README states the BSD-3 license. See the CASRAI Isaac Lab guide.	github.com/isaac-sim/IsaacLab

If you need to bring your own robot description into a simulator, the URDF guide covers the format many tools import.

FAQ

What is robosuite?

An open-source, MuJoCo-based simulation framework and benchmark for robot learning, started by the Stanford Vision and Learning Lab in late 2017 and now part of the ARISE Initiative.

How do I install robosuite?

Create a virtual or Conda environment and run pip install robosuite, then verify with python -m robosuite.demos.demo_random_action. For a source install, clone the ARISE-Initiative repository and run pip3 install -r requirements.txt.

Does robosuite need MuJoCo?

Yes. MuJoCo is the physics backend, and since v1.4 robosuite uses DeepMind’s official MuJoCo Python binding.

How do I cite robosuite?

Cite arXiv:2009.12293 (BibTeX key robosuite2020 in the repository) and state the release you used.

What is the difference between sparse and dense reward?

Sparse reward is a binary success signal from the environment’s success check. Dense reward is shaped to guide stages such as reaching, grasping and lifting.

Sources

• robosuite documentation: overview (read 2026-11-12)
• robosuite documentation: installation (read 2026-11-12)
• robosuite documentation: basic usage (read 2026-11-12)
• robosuite documentation: environments module (read 2026-11-12)
• ARISE-Initiative/robosuite repository (read 2026-11-12)
• Zhu et al., robosuite, arXiv:2009.12293 (read 2026-11-12)
• robomimic project page (read 2026-11-12)
• Isaac Lab repository (read 2026-11-12)