Mitsuba 3

3.8.0 verified Fri May 01 auth: no python

Mitsuba 3 is a research-oriented retargetable forward and inverse renderer, version 3.8.0, with variable release cadence. It provides a Python API for physically based rendering and differentiable rendering.

pip install mitsuba

Common errors

error ImportError: cannot import name 'load_xml' from 'mitsuba' ↓

cause Deprecated load_xml was removed in newer versions. Use mi.load_file.

fix

Replace 'mi.load_xml' with 'mi.load_file'.

error RuntimeError: No variant selected! Use mi.set_variant() before calling any Mitsuba functions. ↓

cause You forgot to set a variant before using the API.

fix

Add 'mi.set_variant('scalar_rgb')' (or appropriate variant) at the beginning of your script.

error AttributeError: module 'mitsuba' has no attribute 'render' ↓

cause Variant not set, or using old API 'mi.render_scene'.

fix

Set variant first: mi.set_variant('scalar_rgb'); then call mi.render(scene).

error OSError: cannot load library: ...libmitsuba-core.so: cannot open shared object file ↓

cause Missing dynamic libraries, typically because mitsuba is not built with the correct variant or installed from source without proper setup.

fix

Install precompiled wheel via 'pip install mitsuba' for your variant (e.g., 'scalar_rgb', 'cuda_ad_rgb').

Warnings

breaking Variant must be set before any scene loading or rendering. Not setting a variant leads to ImportError or runtime errors. ↓

fix Call mi.set_variant('scalar_rgb') (or other variant) at the start of your script.

deprecated mi.load_xml() and mi.render_scene() are deprecated. Use mi.load_file() and mi.render() instead. ↓

fix Replace mi.load_xml with mi.load_file, and mi.render_scene with mi.render.

gotcha Repeated set_variant calls in the same process cause undefined behavior. You can only set variant once per session. ↓

fix Set variant once at the top; avoid calling set_variant again.

gotcha Mitsuba uses a custom memory allocator; mixing with other libraries that use incompatible allocators (e.g., PyTorch with CUDA) may cause segmentation faults. ↓

fix Enable memory pooling via mi.set_memory_pool_enabled(True) or manage allocation scope. For differentiable rendering, use the provided mitsuba.python.autodiff module.

Imports

mitsuba
wrong
```
import mitsuba
```
correct
```
import mitsuba as mi
```
Convention is to import as 'mi' for brevity.
Scene
wrong
```
mitsuba.load_xml('scene.xml')
```
correct
```
mi.load_file('scene.xml')
```
Use load_file to load XML scenes, not load_xml.
render
wrong
```
mitsuba.render_scene(scene)
```
correct
```
mi.render(scene)
```
Render function is 'mi.render'.

Quickstart

Initialize Mitsuba, load the Cornell Box scene, render, and save result.

import mitsuba as mi
mi.set_variant('scalar_rgb')
scene = mi.load_file(mi.cornell_box())
image = mi.render(scene)
mi.util.write_bitmap('out.png', image)
print('Rendered Cornell Box to out.png')