headless-batch-scriptinglisted

# Headless Batch Scripting ## Trigger Use this skill when the user: - Wants to render, export, or process .blend files from a CLI or CI pipeline - Mentions `blender --background`, `--python`, "headless", "batch render", "no UI" - Has an operator script that fails with `RuntimeError: Operator bpy.ops.X.Y.poll() failed, context is incorrect` - Needs to pass arguments to a Blender Python script ## The basic shape ```powershell blender --background --python my_script.py ``` Or with a specific .blend file: ```powershell blender --background scene.blend --python my_script.py ``` Or with arguments after `--`: ```powershell blender --background scene.blend --python my_script.py -- --output out.png --frames 1,5,10 ``` `--background` (or `-b`) tells Blender not to launch a UI window. `--python` (or `-P`) runs a Python script. The script receives `sys.argv` containing everything after the `--` separator. ## What changes without a UI The Blender API is the same in headless mode but several context-dependent behaviors break: | Subsystem | Headless behavior | | --- | --- | | `bpy.context.window`, `bpy.context.area`, `bpy.context.region` | Often `None` | | `bpy.context.active_object` | `None` if no scene is loaded or no active object set | | `bpy.context.selected_objects` | Empty by default | | Most `bpy.ops.<editor>.*` operators | Fail with "context is incorrect" because they expect an editor that does not exist | | Modal operators | Cannot be used; no event loop | | Drag and