Installation¶

MuJoCo-rs¶

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

With visualization/rendering support:

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

Without visualization/rendering support:

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

See Optional Cargo features for information about available Cargo features. We strongly recommend to disable any rendering-related features when rendering is not needed, which will reduce compilation time.

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 --no-default-features --features "auto-download-mujoco"

Then, set the environmental 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.3.7.

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="\path\mujoco\lib\"

One option is to set up your own homebrew file and install pkg-config (see this issue).

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 environmental variable. You can fix these kind 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 environmental 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.

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 also installs the Rust toolchain, however 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 uses clang-13/clang++-13 as the compiler.
Set the environmental variable MUJOCO_STATIC_LINK_DIR to the absolute path of the lib/ subdirectory inside mujoco/build/. 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.