Headless Blender v1.0.0

name: "headless-blender" description: "Render with Blender on a headless VM: background mode, Cycles CPU, robust frame output, and common gotchas."

Headless Blender

Render on machines with no display. Assumes Blender 4.x+ installed.

The invocation

bash
blender -b scene.blend -o //frames/frame-#### -f 1        # single frame
blender -b scene.blend -o //frames/frame-#### -s 1 -e 120 -a  # animation

-b is background mode (no UI). Always render image sequences (PNG), then encode video from frames with ffmpeg -- if a render dies at frame 87, you keep 86 frames instead of nothing.

bash
ffmpeg -y -framerate 24 -i frames/frame-%04d.png \
  -c:v libx264 -pix_fmt yuv420p out.mp4

Headless rendering engine

• EEVEE needs a GPU/EGL context and usually fails headless. Use Cycles with CPU:

python
  scene.render.engine = 'CYCLES'
  scene.cycles.device = 'CPU'
  

• If the blender binary fails to start (missing libEGL etc.), a wrapper that forces software GL (Mesa) fixes startup; rendering still goes through Cycles CPU.

Python script gotchas

• Colors are linear, not sRGB. Values set via default_value on shader sockets are interpreted as linear -- sRGB values you paste in will render washed out. Convert intended sRGB colors to linear first.
• Principled BSDF lobes add up (4.x+). "Transmission Weight" no longer replaces diffuse; for pure glass set diffuse "Weight" to 0 or you get a milky veil.
• Mix Shader Fac order: Fac 0 = first shader input, Fac 1 = second. Double-check when wiring Light Path splits.

Robustness

• Run long renders detached (nohup / backgrounded process) and log to a file; check the log for the completion marker, don't assume.
• Set explicit output paths and overwrite behavior; never rely on the .blend file's saved paths surviving a move.
• Verify the final MP4 with the video-qc checklist before claiming success.