Installation¶

MuJoCo-rs¶

Note

MuJoCo-rs requires Rust 1.88 or newer (MSRV). Run rustup update stable to ensure you are on a supported toolchain.

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

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

With visualization/rendering support:

cargo add mujoco-rs --features "viewer-ui renderer-winit-fallback"

Note

On Windows and macOS the renderer-winit-fallback feature is required whenever the renderer feature is enabled (the build fails otherwise). It is optional on Linux.

Attention

macOS: visualization (the viewer and the renderer) does not work on macOS with the upstream glutin crate. To make it work, patch glutin in your project’s Cargo.toml with the following fork:

[patch.crates-io]
glutin = { git = "https://github.com/davidhozic/glutin", rev = "e95fe97f1857c0498ed2236c0e8d60e5a30a2854" }

See Optional Cargo features for information about available Cargo features. Visualization and rendering features are opt-in to keep compilation fast for headless use cases.

Then MuJoCo installation needs to be configured, as described below. MuJoCo is the actual physics engine that MuJoCo-rs depends on.

Dependencies¶

MuJoCo¶

Dynamic linking (official MuJoCo build)¶

Note

MuJoCo official builds are available only in the form of a shared/dynamic library. This is the preferred way of providing MuJoCo as it involves the least amount of work.

When the goal is to provide MuJoCo as a dynamic dependency, you can either tell MuJoCo-rs to download MuJoCo automatically or you can download MuJoCo yourself.

To make MuJoCo-rs automatically download MuJoCo, enable MuJoCo-rs’s Cargo feature auto-download-mujoco:

cargo add mujoco-rs --features "auto-download-mujoco"

Then, set the environment variable MUJOCO_DOWNLOAD_DIR to the absolute path into which the MuJoCo library will be extracted. Note that a subdirectory will be created automatically in the format mujoco-x.y.z, where x.y.z is the MuJoCo version.

export MUJOCO_DOWNLOAD_DIR=/home/user/libraries/

$env:MUJOCO_DOWNLOAD_DIR="C:\Users\User\Libraries\"

Note

On Linux and macOS, if you somehow managed to register MuJoCo with pkg-config, nothing more is needed. MuJoCo provides no official way to do this, but we still keep the option open.

When providing MuJoCo manually, make sure its version is 3.9.0.

Download MuJoCo from here.

After download and extraction of MuJoCo, you can tell MuJoCo-rs where to find MuJoCo, by setting the MUJOCO_DYNAMIC_LINK_DIR environment variable to the absolute path of the lib/ subdirectory.

When using Linux (bash), the primary variable can be set like so (assuming MuJoCo’s .so file is located inside /path/mujoco/lib/):

export MUJOCO_DYNAMIC_LINK_DIR=/path/mujoco/lib/

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

$env:MUJOCO_DYNAMIC_LINK_DIR="C:\path\mujoco\lib\"

One option is to set up your own Homebrew formula and install pkg-config (see this pull request).

Another option is to copy and link some files:

Open the downloaded .dmg file.
Copy mujoco.framework to the current working directory.
Create a symbolic link to the copied libmujoco.x.x.x.dylib and name it libmujoco.dylib:

ln -s mujoco.framework/Versions/Current/libmujoco.x.x.x.dylib libmujoco.dylib.

Set the primary environment variable:

export MUJOCO_DYNAMIC_LINK_DIR=$(realpath .)

You should now be able to compile and run your crate.

Regardless of whether MuJoCo is downloaded by MuJoCo-rs or you provided it manually, you may encounter runtime errors about the library not being found. This can happen if the library is not located in a standard location nor added to the OS-dependent path environment variable. You can fix these kinds of errors like so:

Either copy libmujoco.so and libmujoco.so.x.y.z to the standard location (i.e., /usr/lib/)

or,

Update the LD_LIBRARY_PATH environment variable. Assuming libmujoco.so is located in /path/to/mujoco/lib/:

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

Place the mujoco.dll file in the current working directory (next to the EXE). Alternatively, the path to the DLL file’s directory can be added to the PATH environment variable. See here for a tutorial on configuring PATH.

Attention

Make sure the PATH variable contains the path to the directory of the .dll file, not of the .lib file. 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. The .lib file is contained in the lib/ directory of the MuJoCo download.

Update the DYLD_LIBRARY_PATH environment variable.

Assuming libmujoco.dylib is located in /path/to/mujoco/lib/:

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

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. The C++ viewer is exposed through the cpp-viewer Cargo feature, which requires this static-linking setup.

To build statically linkable libraries, perform the following steps:

Clone MuJoCo-rs’s 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=OFF -DMUJOCO_BUILD_EXAMPLES:BOOL=OFF
cmake --build build --parallel --target glfw libmujoco_simulate --config=Release
```
This was tested with the gcc compiler.

Note that -DCMAKE_INTERPROCEDURAL_OPTIMIZATION:BOOL=OFF disables link-time optimization, thus resulting in slightly lower performance. Enabling it causes compatibility problems on the Linux platform. See the attention block below for more info.

See also

See this Dockerfile for a reproducible build environment which, to our knowledge, matches MuJoCo’s official build environment. The Dockerfile includes commented-out commands for installing the Rust toolchain and for using clang-13/clang++-13 as the compiler. Our testing showed that static libraries built in the container also work outside of the container, even on the rust-lld linker.

The Dockerfile defines a container running Ubuntu 22.04 and installs clang-13 alongside build-essential. See the commented-out cmake commands in the Dockerfile for the recommended compiler flags.
Set the environment variable MUJOCO_STATIC_LINK_DIR to the absolute path of the lib/ subdirectory inside mujoco/build/ (on some distributions, e.g. Fedora/RHEL/Arch, the directory may be lib64/). Bash example:
```
export MUJOCO_STATIC_LINK_DIR=/path/mujoco/build/lib/
```
Build MuJoCo-rs
```
cargo build
```

Attention

Link-time optimization

Above CMake configuration command disables link-time optimization (LTO). This results in worse performance but allows the compiled code to be used with the rust-lld linker, which is the default linker since Rust 1.90.0 on the x86_64-unknown-linux-gnu target.

If performance is critical for you, link-time optimization of MuJoCo code can be enabled during configuration:

cmake -B build -S . -DCMAKE_INTERPROCEDURAL_OPTIMIZATION:BOOL=ON ...

When LTO is enabled, the system linker must be used, because rust-lld doesn’t know how to read extra LTO information produced by other linkers:

RUSTFLAGS="-C linker-features=-lld" cargo build

In performance critical cases, it is also recommended to use the official MuJoCo shared (dynamic) libraries, which are generally more optimized. Performance gain with LTO enabled on static builds is about 10% more steps per second.