blender-headless

name	blender-headless
description	Run Blender headlessly as a command line application to execute python script processing, rendering, or automation. Use this skill when asked to render 3D scenes, manipulate .blend files, or automate Blender operations without the GUI.

Blender Headless Automation Skill

Blender can be run strictly as a background/headless process. When combined with Python scripts (bpy module), an AI agent can fully manipulate 3D scenes, alter materials, and execute renders entirely from the terminal.

Core Command & Flags

If running on Linux, standard execution involves the following flags:

blender -b -P my_script.py

Or to act on an existing .blend file:

blender -b my_scene.blend -P script.py

• -b or --background: Run without the GUI. This is the most critical flag.
• -P or --python: Executes the specified Python script.

Passing Arguments to Python Scripts

Passing custom arguments into the Python script (e.g., output paths, numbers, configuration) requires a specific syntax to ensure Blender doesn't try to parse them as engine flags.

Command Line Execution: Use the double-dash -- to separate Blender arguments from Python script arguments.

blender -b -P script.py -- --custom-arg "value" --output "/path/out.obj"

Python Script (script.py) Parsing: When parsing arguments inside your script using argparse, you must discard all arguments before the --.

import argparse
import sys
import bpy

def get_args():
    parser = argparse.ArgumentParser()
    # Get all script args
    _, all_arguments = parser.parse_known_args()
    
    # Isolate only the arguments passed AFTER the double-dash
    double_dash_index = all_arguments.index('--')
    script_args = all_arguments[double_dash_index + 1: ]
    
    # Add parser rules
    parser.add_argument('-c', '--custom-arg', help="A custom argument")
    parser.add_argument('-o', '--output', help="Output file path")
    
    # Parse the isolated args
    parsed_script_args, _ = parser.parse_known_args(script_args)
    return parsed_script_args

if __name__ == "__main__":
    args = get_args()
    print(f"Value: {args.custom_arg}")
    
    # Do 3D operations via bpy
    bpy.ops.mesh.primitive_cube_add(location=(0, 0, 0))
    
    # Save the scene or render
    bpy.ops.export_scene.obj(filepath=args.output)

Important AI Execution Considerations

• When rendering, if a specific .blend file isn't provided, Blender opens with its default scene (a cube, light, and camera).
• Blender Python (bpy) operations generally overwrite elements, so be explicit about deleting default starting objects if they interfere with your procedural generation: bpy.ops.object.select_all(action='SELECT'); bpy.ops.object.delete(use_global=False)
• Always ensure absolute paths are used for input and output.