Installation¶

MuJoCo-rs¶

MuJoCo-rs can be added to your project like so:

With visualization/rendering support:
```
cargo add mujoco-rs
```

Without visualization/rendering support:

cargo add mujoco-rs --no-default-features

Then additional dependencies need to be installed/configured:

MuJoCo (required): The actual physics engine, which is a C library.
Other build dependencies. These are only required when visualization or rendering is enabled.

Dependencies¶

MuJoCo¶

Because MuJoCo-rs doesn’t directly bundle MuJoCo, the latter, in the form of a pre-built library or source code, must be downloaded or compiled. Make sure to download or compile MuJoCo version 3.3.5.

Compilation of MuJoCo-rs incudes linking the MuJoCo library. This requires some environmental variables to be set, which tell MuJoCo-rs where to obtain the MuJoCo library.

The linking process depends on whether you plan to dynamically link (recommended), statically link or statically link with support for the C++ based viewer (instead of the Rust-native one).

Dynamic linking¶

Dynamic linking is OS-dependent. To dynamically link, the primary variable MUJOCO_DYNAMIC_LINK_DIR must be set.

Linux¶

When using Linux (bash), the primary variable can be set like so:

export MUJOCO_DYNAMIC_LINK_DIR=/path/mujoco/lib/

This is assuming MuJoCo’s .so file is located inside /path/mujoco/lib/.

Additionally, in the event that the user’s program refuses to run and outputs something like:

“error while loading shared libraries: libmujoco.so”

the path to the MuJoCo library’s directory must also be added to LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/mujoco/lib/

Windows¶

When using Windows (powershell), the primary variable can be set like so:

$env:MUJOCO_DYNAMIC_LINK_DIR = "/path/mujoco/lib/"

Additionally, the library in DLL form must be added to the PATH variable. For help adding the path /path/mujoco/bin/ to the PATH variable, see here. Alternatively, the DLL file can be placed in the working directory.

Attention

Make sure the PATH variable contains the path to the .dll file, NOT .lib. The .lib file is used only for compilation, while the .dll is used at runtime. The .dll file is contained in the bin/ directory of the MuJoCo download.

MacOS¶

MacOS is currently untested.

Static linking¶

Official MuJoCo builds include the precompiled MuJoCo library only in its shared (dynamic) form. To statically link, you’ll need to compile MuJoCo yourself. MuJoCo’s build system doesn’t (yet) support static linking, which is why we provide a modified MuJoCo repository with static linking support.

While MuJoCo-rs already provides a Rust-native 3D viewer, we understand that some projects wish to use the original C++ based 3D viewer (also named Simulate). To enable this, the modified MuJoCo repository also includes changes that support a safe interface between Rust and the C++ Simulate code.

To build statically linkable libraries, perform the following steps:

Clone the MuJoCo-rs repository,
Change your directory to the cloned repository,

Run commands:

git submodule update --init --recursive
cd ./mujoco/
cmake -B build -S . -DBUILD_SHARED_LIBS:BOOL=OFF -DMUJOCO_HARDEN:BOOL=OFF -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_INTERPROCEDURAL_OPTIMIZATION:BOOL=ON -DMUJOCO_BUILD_EXAMPLES:BOOL=OFF -DCMAKE_EXE_LINKER_FLAGS:STRING=-Wl,--no-as-needed
cmake --build build --parallel --target libsimulate --config=Release

The builds are tested with the gcc compiler.

Set the environmental variable MUJOCO_STATIC_LINK_DIR. Bash example:
```
export MUJOCO_STATIC_LINK_DIR=/path/mujoco/lib/
```
Build MuJoCo-rs
```
cargo build
```
Attention

On Linux, you may need to tell Rust to use the system linker instead of rust-lld. This is a problem with LTO and different linkers being used to link MuJoCo-rs and MuJoCo. The problem will be addressed in a future MuJoCo-rs release.
```
RUSTFLAGS="-C linker-features=-lld" cargo build
```

Build dependencies (visualization/rendering only)¶

When visualization or rendering is required, MuJoCo-rs may require additional build-time dependencies. These are needed to build GLFW — a library used for window and OpenGL context management.

If you do not require the use of 3D renderer or 3D viewer, you can avoid build-time dependencies by disabling the default features:

# Disables viewer and renderer features.
cargo add mujoco-rs --no-default-features

When there is a need for rendering/visualization support, dependencies are OS-dependent.

Windows¶

On Windows, no additional build-time dependencies are required. GLFW is obtained automatically. If you run into problems, please submit an issue.

Hint

Optionally, instead of using the pre-built, GLFW can be compiled from scratch by enabling MuJoCo-rs’s glfw-build Cargo feature.

Linux¶

On Linux, MuJoCo-rs will try to use the GLFW installed in your Linux distribution, but only when the installed version is GLFW 3.4. Linkage will be auto-configured through pkg-config. In such case, no additional dependencies are needed. For example, Ubuntu 25.04+ and Fedora 42 use GLFW 3.4.

If your distribution uses an older GLFW version, GLFW 3.4 will be compiled. This requires CMake and common C build tools to be installed. E.g., for Ubuntu/Debian distributions run:

sudo apt install -y build-essential cmake

MacOS¶

We don’t test MacOS builds, however the process should be the same as for Linux.