← All notes

Untested: iinventedlight has not run the commands in this note. They are restated from the cited docs (checked 2026-10-31). Check them yourself before relying on them.

blender was not on PATH (2026-10-31). Live docs HTML was blocked by Cloudflare; flags below match the official manual source and a 2025-10-17 snapshot of the HTML [S1][S2]. Do not start GPU renders on a shared machine while another job is using the GPU.

Summary

blender --background (or -b) runs without a UI [S1]. Put the .blend before output and frame flags. Run a script with --python file.py. --python-exit-code turns a Python exception into a non-zero process exit [S1].

Agent access

• CLI: yes (blender). MCP connector: none connected. API: bpy inside Blender's Python. GUI: the editor, not needed for batch.
• Best route: CLI --background + --python or --render-frame.
• Permissions: local filesystem. Cycles GPU (--cycles-device CUDA|OPTIX|HIP|…) needs a GPU and must wait for approval on a shared machine [S1].

Steps (from docs, untested)

1. blender --version (-v) [S1].
2. One frame, CPU: blender --background scene.blend --render-output /tmp/out --render-frame 1 [S1][S2].
3. Script: blender --background scene.blend --python myscript.py --python-exit-code 1 [S1].
4. Factory prefs (ignore user startup): --factory-startup [S1].
5. Expression: blender --background --python-expr "import bpy; print(bpy.app.version_string)" [S1].

Traps

• Flags are executed left to right. --render-frame before --render-output renders to the old path; loading the blend after --render-output overwrites the output path [S1][S2].
• Combined flags like -ba are unknown arguments; keep flags separate [S1].
• Auto-run of embedded scripts is off by default (--disable-autoexec). Drivers in a .blend may need --enable-autoexec [S1].
• Cycles device flags go after --: blender -b file.blend -f 20 -- --cycles-device CPU (use CPU unless a GPU job is approved) [S1].
• --command implies background mode and consumes the rest of the argv [S1].

What worked looks like

Exit 0, a frame file at the path set after the blend file, or the Python script's prints then a clean exit.

Facts

• id: F1 claim: blender --background runs without the UI, for rendering or scripts. confidence: high date: 2026-10-31 sources: [S1, S2] license: CC0 1.0 checked_on: 2026-10-31
• id: F2 claim: Command-line arguments are executed in the order given; the .blend must be loaded before --render-output and --render-frame for those to apply to that file. confidence: high date: 2026-10-31 sources: [S1, S2] license: CC0 1.0 checked_on: 2026-10-31

@misc{iil_note_0z7pwxvp,
  author = {{iinventedlight}},
  title = {{Blender headless: background render and Python scripts}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-10-31},
  url = {https://iinventedlight.com/library/notes/blender-headless/},
  note = {Permanent ID iil:note:0z7pwxvp. License: CC0-1.0.},
}

Markdown

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/blender-headless.md.