Blender Headless
Automation
Drive Blender in background mode from a visual pipeline. Import geometry, configure Cycles/EEVEE render settings, export to USD or glTF, render animation sequences — all without opening the GUI.
How It Works
Blender is launched with blender --background and a Python runner script. The runner reads the action list from a temporary JSON payload and dispatches each action using bpy inside the same Blender process. Results are written to a second JSON file and parsed back into the graph.
Background mode
Blender starts with --background. No window, no GPU display requirement. Works in headless servers, CI, and render farms.
bpy-native actions
Every action calls real bpy operators. Version-aware wrappers handle API differences between Blender 3.6, 4.0, and 4.2+.
Structured results
Each action returns ok/error. The executor surfaces executed_actions, skipped_actions, and process stdout/stderr for full traceability.
blender --background \
--python /tmp/runner_abc123.py \
-- /tmp/payload_abc123.json /tmp/results_abc123.jsonExample: Set Render Settings → Render Animation
async def execute(self, inputs):
actions = list(inputs.get("actions_in") or [])
actions.append({
"type": "set_render_settings",
"render_engine": "CYCLES",
"resolution_x": 1920,
"resolution_y": 1080,
"samples": 128,
"use_gpu": True,
"output_path": "/render/frames/frame_",
"file_format": "EXR",
"frame_start": 1001,
"frame_end": 1120,
})
return {"actions_out": actions, "exec_out": True}Available Actions
18 actions. Each maps to a type key in the action dict.
| Action Type | Description |
|---|---|
| open_blend | Open a .blend file inside Blender |
| new_blend | Load factory settings (optionally empty scene) |
| save_blend | Save the current file to disk |
| scene_info | Read scene name, frame range, FPS, renderer, resolution, object list, collections |
| set_frame_range | Set scene frame_start, frame_end, and optional fps |
| import_obj | Import .obj — version-aware for Blender 4.0+ new IO |
| import_fbx | Import .fbx geometry/rig file |
| import_alembic | Import Alembic .abc cache |
| import_gltf | Import .glb or .gltf file |
| export_obj | Export scene or selection as .obj |
| export_fbx | Export as .fbx with baked animation options |
| export_alembic | Export Alembic cache with frame range — version-aware kwarg handling |
| export_gltf | Export as .glb or .gltf with animation |
| export_usd | Export as USD with animation, materials, normals |
| set_render_settings | Configure render engine (CYCLES, EEVEE, EEVEE_NEXT), resolution, samples, output, GPU |
| render | Render a still frame or full animation sequence |
| bake_animation | Bake constraints/simulation to keyframes via NLA bake |
| custom_python | Execute arbitrary Python code inside Blender (bpy available) |
Supported Blender Versions
| Version | Notes |
|---|---|
| Blender 4.3 | Latest stable — new IO operators |
| Blender 4.2 | LTS — default; stable for production |
| Blender 4.1 | Stable — new EEVEE Next engine |
| Blender 4.0 | Stable — OBJ import API change |
| Blender 3.6 | LTS legacy — full support |
Version is selected via a dropdown on the Blender Headless node. The blender.exe path auto-fills to the default installation location and can be overridden. Version-aware wrappers handle OBJ import/export API differences between Blender 3.x and 4.x.
USD Pipeline Support
The export_usdaction uses Blender's native USD exporter. Configure animation, materials, UV maps, normals, and hair exports in a single action dict.
actions.append({
"type": "export_usd",
"usd_path": "/pipeline/assets/character_hero/v003/character_hero.usdc",
"export_animation": True,
"export_materials": True,
"export_uvmaps": True,
"export_normals": True,
"export_hair": False,
})Maya Headless
Same action-list pattern for Autodesk Maya 2022–2026
→Deadline Integration
Submit Blender render jobs to Thinkbox Deadline
→Examples Library
Browse VFX workflow examples using these nodes
→