Native Viewers#
Studio provides two ways to run in a native desktop window, built on the same shared C++ components so both look and behave nearly identically:
MuJoCo Studio app (C++): Prebuilt standalone desktop application for inspecting models out of the box, extending in C++, or compiling to WebAssembly to run serverless in the browser (MuJoCo Live).
Python
NativeViewer: Drives or attaches to a Python simulation loop and supports Python plugins.
Choose NativeViewer when scripting or extending in Python, and the C++ application when extending in C++ or
targeting serverless WebAssembly; any custom components meant to be shared across both should be written in C++ and
bound to Python (see C++ Components).
Standalone Application#
Every GitHub release includes a prebuilt standalone Studio application alongside simulate, rendered via Filament:
macOS (
.dmg): Packaged as theMuJoCoStudio.appbundle; double-click to launch directly from the disk image or drag it into/Applicationsto install.Windows (
.zip): Packaged asbin\mujoco_studio.exein the extracted archive; double-click in File Explorer or launch from a terminal.Linux (
.tar.gz): Shipped asbin/mujoco_studioin the extracted archive.
Once open, load .xml, .mjb, or .mjz models from the File menu or by dragging and dropping onto the
window. From a terminal on any platform, you can also pass a model path (positional or --model_file) and a --gfx
rendering backend:
macOS: /Applications/MuJoCoStudio.app/Contents/MacOS/mujoco_studio model/humanoid/humanoid.xml
Windows: bin\mujoco_studio model\humanoid\humanoid.xml
Linux: ./bin/mujoco_studio model/humanoid/humanoid.xml
To build mujoco_studio from source or link custom C++ plugins, see Build & Launch in
C++.
Python NativeViewer#
In Python, NativeViewer (native_viewer.py) renders both the 3D
scene and Dear ImGui UI locally in an SDL2 desktop window or offscreen buffer via
Filament. Use blocking mode (launch_native.run) when Studio drives the simulation
loop, or non-blocking mode (launch_native.launch) when attaching a viewer to your own Python loop.
Blocking Mode#
To open the standalone Studio viewer from the command line with optional plugin files and hot reload:
python -m mujoco.studio.viewer \
--model=path/to/model.xml \
--gfx=opengl \
--plugins=path/to/my_plugin.py \
--hot_reload=all
From Python, launch_native.run starts NativeViewer
and runs the blocking simulation sync loop until the window closes. Pass model_path=...
to load a model file on the simulation thread so UI Reload and model hot reload stay
enabled, or pass an in-memory model=... with optional data=...:
from mujoco.studio import app as studio_app
from mujoco.studio import launch_native
from mujoco.studio import viewer_protocol
config = viewer_protocol.ViewerConfig(title='MuJoCo Studio', gfx='opengl')
launch_native.run(
config,
model_path='humanoid.xml', # Or model=model, data=data for an in-memory model.
plugins=[studio_app.App(), *studio_app.SIM_PLUGINS],
)
Non-Blocking Mode#
When attaching NativeViewer to an existing Python loop—such as an RL training loop, trajectory replay script, or
test—use launch_native.launch as a non-blocking context
manager. It starts NativeViewer on a daemon thread and returns a ViewerHandle (viewer_handle.py) to the calling thread:
import time
import mujoco
from mujoco.studio import app as studio_app
from mujoco.studio import launch_native
model = mujoco.MjModel.from_xml_path('humanoid.xml')
data = mujoco.MjData(model)
with launch_native.launch(plugins=[studio_app.App()]) as handle:
while handle.is_running():
tick = time.perf_counter()
model, data = handle.sync(model, data)
mujoco.mj_step(model, data)
time.sleep(max(0.0, model.opt.timestep - (time.perf_counter() - tick)))
Key details when driving a ViewerHandle loop directly:
Always rebind
model, data = handle.sync(model, data)on every iteration.sync()publishesmodelanddataif your script created a new model object, and returns replacementmodelanddataobjects whenever UI Reload, a dropped file, or a plugin’shandle.set_model()swaps the active model.Stepping and pacing:
handle.sync()never sleeps. If you omitStepControl(), advancedataand pace the loop yourself afterhandle.sync(); if you include*studio_app.SIM_PLUGINS,StepControl()steps and paces physics insidehandle.sync()duringStepEvent.Mutations: Keep
model.optmutations inside step-event handlers soViewerHandle.sync()’s diff-based sync detects and forwards them to the viewer.macOS (``mjpython``): AppKit requires native windows to be created and serviced on the OS main thread. Blocking mode (
python -m mujoco.studio.viewerandlaunch_native.run) works under standardpython, whereas non-blockinglaunch_native.launchrequires running your script withmjpython(unlike launch_web, which works under standardpython).
See custom_sim_loop.py for a complete non-blocking example that mirrors viewer pause and playback-speed controls while dynamically rebuilding the scene.
Rendering Backends#
Set ViewerConfig.gfx or pass --gfx on the command line to select the native Filament backend:
''(default): Uses the platform default native Filament backend.'opengl'/'vulkan': Hardware-accelerated OpenGL or Vulkan desktop window.'opengl_headless': Offscreen OpenGL context without a visible window, suited for automated tests and offscreen rendering.'opengl_software'/'vulkan_software': Software-rasterized OpenGL or Vulkan for headless CI machines without GPUs.
On Linux, direct window rendering expects X11 ('opengl' is rejected under Wayland). In a Wayland session, omitting
gfx falls back to 'opengl_headless'; for direct GPU presentation, use an X11 session.