{"id":24039,"library":"mitsuba","title":"Mitsuba 3","description":"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.","status":"active","version":"3.8.0","language":"python","source_language":"en","source_url":"https://github.com/mitsuba-renderer/mitsuba3","tags":["rendering","differentiable rendering","computer graphics","physically based rendering"],"install":[{"cmd":"pip install mitsuba","lang":"bash","label":"Stable"}],"dependencies":[],"imports":[{"note":"Convention is to import as 'mi' for brevity.","wrong":"import mitsuba","symbol":"mitsuba","correct":"import mitsuba as mi"},{"note":"Use load_file to load XML scenes, not load_xml.","wrong":"mitsuba.load_xml('scene.xml')","symbol":"Scene","correct":"mi.load_file('scene.xml')"},{"note":"Render function is 'mi.render'.","wrong":"mitsuba.render_scene(scene)","symbol":"render","correct":"mi.render(scene)"}],"quickstart":{"code":"import mitsuba as mi\nmi.set_variant('scalar_rgb')\nscene = mi.load_file(mi.cornell_box())\nimage = mi.render(scene)\nmi.util.write_bitmap('out.png', image)\nprint('Rendered Cornell Box to out.png')","lang":"python","description":"Initialize Mitsuba, load the Cornell Box scene, render, and save result."},"warnings":[{"fix":"Call mi.set_variant('scalar_rgb') (or other variant) at the start of your script.","message":"Variant must be set before any scene loading or rendering. Not setting a variant leads to ImportError or runtime errors.","severity":"breaking","affected_versions":"3.x"},{"fix":"Replace mi.load_xml with mi.load_file, and mi.render_scene with mi.render.","message":"mi.load_xml() and mi.render_scene() are deprecated. Use mi.load_file() and mi.render() instead.","severity":"deprecated","affected_versions":"3.0 - 3.8"},{"fix":"Set variant once at the top; avoid calling set_variant again.","message":"Repeated set_variant calls in the same process cause undefined behavior. You can only set variant once per session.","severity":"gotcha","affected_versions":"3.x"},{"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.","message":"Mitsuba uses a custom memory allocator; mixing with other libraries that use incompatible allocators (e.g., PyTorch with CUDA) may cause segmentation faults.","severity":"gotcha","affected_versions":"3.x"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Replace 'mi.load_xml' with 'mi.load_file'.","cause":"Deprecated load_xml was removed in newer versions. Use mi.load_file.","error":"ImportError: cannot import name 'load_xml' from 'mitsuba'"},{"fix":"Add 'mi.set_variant('scalar_rgb')' (or appropriate variant) at the beginning of your script.","cause":"You forgot to set a variant before using the API.","error":"RuntimeError: No variant selected! Use mi.set_variant() before calling any Mitsuba functions."},{"fix":"Set variant first: mi.set_variant('scalar_rgb'); then call mi.render(scene).","cause":"Variant not set, or using old API 'mi.render_scene'.","error":"AttributeError: module 'mitsuba' has no attribute 'render'"},{"fix":"Install precompiled wheel via 'pip install mitsuba' for your variant (e.g., 'scalar_rgb', 'cuda_ad_rgb').","cause":"Missing dynamic libraries, typically because mitsuba is not built with the correct variant or installed from source without proper setup.","error":"OSError: cannot load library: ...libmitsuba-core.so: cannot open shared object file"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}