mujofil 0.1.4

MuJoCo + Google Filament — high-fidelity, faster-than-OpenGL PBR rendering for MuJoCo

MuJoFil — MuJoCo + Google Filament

High-fidelity, physically-based rendering for MuJoCo, powered by Google Filament instead of the legacy fixed-function OpenGL path — sharper materials, real image-based lighting, and faster frames on modern GPUs.

pip install mujofil

To install the GPU/warp edition together with the base package:

pip install "mujofil[warp]"

This keeps mujofil as the main package while pulling in mujofil-warp as an optional extra dependency.

📖 Full documentation: docs/ — getting started, API guide, feature reference, cookbook & troubleshooting.

🚀 Running physics on the GPU? For MJWarp (thousands of GPU worlds) with zero-copy torch.cuda observations, use the GPU edition, mujofil-warp.

That's it. The Filament engine is statically compiled into the wheel and the material packages ship inside it, so there's no separate SDK, no compiler, and no PYTHONPATH setup. MuJoCo itself comes from its own pip wheel (a dependency).

⚠️ One thing pip can't install for you: a Vulkan GPU driver

MuJoFil renders on the GPU via Vulkan (with an OpenGL fallback). That driver is part of your operating system and cannot be bundled in a wheel. MuJoFil detects this for you — if it's missing you'll see a clear message on first import mujofil, and mujofil-doctor prints exactly what to install:

OS	Install command
Ubuntu/Debian	sudo apt install libvulkan1 mesa-vulkan-drivers vulkan-tools
Fedora	sudo dnf install vulkan-loader mesa-vulkan-drivers vulkan-tools
Arch	sudo pacman -S vulkan-icd-loader vulkan-tools <gpu-vulkan-driver>
macOS	LunarG Vulkan SDK (MoltenVK): https://vulkan.lunarg.com/sdk/home#mac
Windows	Latest GPU driver, or LunarG SDK: https://vulkan.lunarg.com

NVIDIA GPUs also need the proprietary driver. Headless/no-GPU machines can use the software rasterizer (mesa-vulkan-drivers, "lavapipe"). After installing, run mujofil-doctor to confirm.

Verify your setup

mujofil-doctor      # prints a GPU/Vulkan diagnostic; exit 0 = ready to render

Quick start

import mujoco
from mujofil import VFRenderer, RenderConfig

model = mujoco.MjModel.from_xml_path("scene.xml")
data = mujoco.MjData(model)

r = VFRenderer(model, RenderConfig(width=1920, height=1080))
mujoco.mj_step(model, data)
rgb = r.render(data)        # (H, W, 3) uint8

What ships in the wheel

• mujofil/_vf_mujoco_native.*.so — the Filament renderer (Filament linked statically; only libc++/libunwind bundled alongside via auditwheel).
• mujofil/materials/*.filamat — precompiled Filament material packages.
• Pure-Python API (VFRenderer, RenderConfig, VFRenderWrapper).

MuJoCo is not bundled — the bindings read mjModel/mjData through pointers and call no MuJoCo functions, so the mujoco pip package satisfies it at runtime.

Requirements

• A GPU with a working Vulkan (preferred) or OpenGL driver — same as any realtime renderer. For headless CI, a software Vulkan (e.g. lavapipe) works.
• Linux x86-64 (manylinux wheels). macOS / Windows wheels are produced by the same cibuildwheel config.

Building from source

export FILAMENT_DIR=/path/to/filament      # a Filament release
pip install .                              # scikit-build-core + CMake

Multi-platform release wheels are built in CI with cibuildwheel.

License

Apache 2.0 License