Mastering the Blender Command Line Interface (CLI): The U...

This guide covers the Blender CLI: basic syntax, the commands you'll actually use for rendering and Python scripting, and the failure modes that eat an afternoon. Everything here is checked against Blender 4.4's built-in help and official manual.

Why use the Blender CLI?

The obvious reason is that you can't click buttons on a machine with no display. If you render on a server or a farm node, the CLI isn't an optimization, it's the only option.

The less obvious reason is repetition. Once a task is a command, it can be scripted, queued, run across fifty files, or dropped into a pipeline alongside other tools. And some parameters are simply faster to set as a flag than to hunt for in the interface.

Launching the CLI

Open your system's terminal or command prompt:

Windows: Open Command Prompt (type cmd in the Start menu) or PowerShell. Navigate to Blender's installation directory (e.g., cd "C:\Program Files\Blender Foundation\Blender 4.4"). Then run blender.exe.
macOS: Open Terminal (Applications > Utilities). Navigate to the Blender application bundle: cd /Applications/Blender.app/Contents/MacOS. Then run ./Blender.
Linux: Open your terminal. If Blender is in your system's PATH (common with package manager installs), you can just type blender. Otherwise, navigate to Blender's installation directory and run ./blender.

For detailed, platform-specific instructions, always refer to the official Blender Manual section on Launching from the Command Line.

Once launched with CLI arguments, Blender might not open its GUI, especially if you use commands like -b for background mode.

Basic concepts

Two things to understand before the command list:

Command structure

The general syntax for Blender CLI commands is: blender [args ...] [file] [args ...]

blender: The command to run the Blender executable.
[args ...]: Global arguments that affect Blender's overall behavior.
[file]: (Optional) The path to a .blend file you want to operate on.
[args ...]: Arguments that might be specific to the file or operation that follows.

Argument order matters

This is the one that catches everyone. Arguments are executed in the order they are given. A misplaced argument doesn't error out, it just quietly does the wrong thing.

For example: blender --background test.blend --render-frame 1 --render-output "/tmp" This will not render to /tmp because --render-frame 1 executes before the output path is set.

blender --background --render-output /tmp test.blend --render-frame 1 This also will not render to /tmp because loading test.blend overwrites the render output that was set before it.

The correct order in this case would be: blender --background test.blend --render-output /tmp --render-frame 1 This works as expected because the blend file is loaded first, then the output path is set, and finally, the frame is rendered.

File paths

When specifying file paths for render outputs or Python scripts:

Absolute paths: the full path (e.g., /home/user/renders/ or C:\Users\user\renders\).
Relative paths: a leading // means "relative to the currently open .blend file". If your blend file is /path/to/project.blend, then //render_output/ refers to /path/to/render_output/.

Core CLI commands

1. Rendering

This is what most people come to the CLI for.

-b or --background Run Blender in background (headless) mode. Essential for rendering without the GUI. Audio is usually disabled in this mode.

Example: blender -b my_scene.blend -a
-a or --render-anim Render all frames from the start to the end frame defined in the .blend file (or overridden by -s and -e).

Example: blender -b my_scene.blend -o //renders/anim_frame_#### -F PNG -a

-S <name> or --scene <name> Set the active scene for rendering.

Example: blender -b my_project.blend -S "Shot_02" -a
-f <frame> or --render-frame <frame> Render a specific frame or a set of frames.
- For a single frame: -f 10 (renders frame 10)
- Relative frames: -f +5 (renders 5 frames after the scene's start frame), -f -5 (renders 5 frames before the scene's end frame).
- Comma-separated list: -f 1,5,10 (renders frames 1, 5, and 10)
- Range: -f 1..5 (renders frames 1, 2, 3, 4, and 5)
Example: blender -b my_scene.blend -f 42
-s <frame> or --frame-start <frame> Set the start frame for rendering.

Example: blender -b my_scene.blend -s 10 -e 50 -a
-e <frame> or --frame-end <frame> Set the end frame for rendering.

Example: blender -b my_scene.blend -s 10 -e 50 -a
-j <frames> or --frame-jump <frames> Set the frame step. For example, -j 2 renders every second frame.

Example: blender -b my_scene.blend -j 3 -a
-o <path> or --render-output <path> Set the render output path and filename.
- Use // for paths relative to the .blend file.
- # characters are replaced by the frame number, with padding.
  - output_##.png becomes output_01.png, output_02.png, etc.
  - output_######.png becomes output_000001.png.
- If no # is present, Blender appends #### to the filename.
Example: blender -b my_scene.blend -o //renders/frame_### -F PNG -a
-E <engine> or --engine <engine> Specify the render engine (e.g., CYCLES, EEVEE, WORKBENCH). Use -E help to list available engines.

Example: blender -b my_scene.blend -E CYCLES -f 1
-t <threads> or --threads <threads> Set the number of CPU threads to use (0 for all available system processors).

Example: blender -b my_scene.blend -t 4 -a

Specific Rendering Example: Render frames 10 to 20 of animation_project.blend using the Cycles engine on an NVIDIA OptiX GPU, outputting as EXR files to a relative folder named hires_frames:

blender -b animation_project.blend \
-S "MainScene" \
-E CYCLES \
-o //hires_frames/shot1_#### \
-F OPEN_EXR \
-s 10 \
-e 20 \
-a \
-- --cycles-device OPTIX

Cycles Render Options: These options must follow a double dash (--).

--cycles-device <device> Set the Cycles render device. Options include CPU, CUDA, OPTIX, HIP, ONEAPI, METAL. You can also append +CPU to a GPU device (e.g., CUDA+CPU).

Example: blender -b my_scene.blend -E CYCLES -f 1 -- --cycles-device OPTIX
--cycles-print-stats Log statistics about render memory and time usage.

Format Options:

-F <format> or --render-format <format> Set the output image or video format. Common options: PNG, JPEG, OPEN_EXR, FFMPEG.

Example: blender -b my_scene.blend -o //my_render -F OPEN_EXR -f 1
-x <bool> or --use-extension <bool> Set to 1 to add the file extension to the output filename, 0 to disable. By default, Blender doesn't add the extension automatically when rendering through CLI.

When set to 1, Blender will append the appropriate extension based on your chosen output format (e.g., .png, .jpg, .exr). This makes files immediately recognizable and usable by other applications without renaming.

When set to 0, Blender omits the extension, which can be useful for custom post-processing scripts that need to handle files in specific ways.

Example with extension enabled: blender -b my_scene.blend -o //my_render -F PNG -x 1 -f 1 Output: my_render0001.png

Example with extension disabled: blender -b my_scene.blend -o //my_render -F PNG -x 0 -f 1 Output: my_render0001

2. Python scripting

Running a script from the CLI is how you modify scenes, automate tasks, or perform custom exports without touching the interface.

-P <filepath> or --python <filepath> Run the specified Python script file.

Example: blender -b my_scene.blend -P my_script.py
--python-text <name> Run a Python script from a text block within the .blend file.

Example: blender -b my_scene.blend --python-text "MyInternalScript"
--python-expr <expression> Execute a single Python expression.

Example: blender --python-expr "import bpy; bpy.data.objects['Cube'].location.x = 5.0"
--python-console Run Blender with an interactive Python console.
-y or --enable-autoexec / -Y or --disable-autoexec Enable or disable automatic execution of Python scripts within .blend files (drivers, startup scripts). Disabled by default for security.
--addons <addon(s)> Enable a comma-separated list of add-ons.

Example: blender --addons "node_wrangler,my_custom_addon"

Specific Python Scripting Example: Let's say you have a script move_and_render.py:

# move_and_render.py
import bpy
import sys
 
# Get custom argument (e.g., new x_location)
args = sys.argv[sys.argv.index("--") + 1:]
new_x_location = float(args[0]) if args else 0.0
 
# Ensure 'Cube' exists
if "Cube" in bpy.data.objects:
    bpy.data.objects["Cube"].location.x = new_x_location
    print(f"Moved Cube to X: {new_x_location}")
else:
    print("Error: Cube not found in scene.")
    sys.exit(1) # Exit with an error code
 
# Set render output
bpy.context.scene.render.filepath = "//script_render_output/frame_##"
bpy.context.scene.render.image_settings.file_format = 'PNG'
 
# Render a single frame
bpy.ops.render.render(write_still=True, animation=False, scene=bpy.context.scene.name)
print(f"Rendered frame {bpy.context.scene.frame_current} to {bpy.context.scene.render.filepath}")

You would run this with:

blender -b my_scene.blend --python-use-system-env -P move_and_render.py -- 10.0

This command runs Blender in the background, loads my_scene.blend, allows Python to use system environment variables, executes move_and_render.py, and passes 10.0 as a custom argument to the script. The script then moves the "Cube" object to X=10.0 and renders the current frame to //script_render_output/.

Passing Arguments to Python Scripts: To pass custom arguments to your Python script, place them after the -- separator. These arguments will then be accessible in your script via sys.argv.

Example: blender -b -P my_script.py -- --my-arg value --another-option Inside my_script.py:

import sys
args = sys.argv[sys.argv.index("--") + 1:] # Get arguments after --
print(f"My custom arguments: {args}")
# args would be ['--my-arg', 'value', '--another-option']

3. Animation playback

Blender can act as a command-line animation player, which is handy for reviewing a rendered sequence at its native resolution and frame rate without importing it into an editor first.

-a <options> <file(s)> (when not used with -b) Launches Blender's animation player to view image sequences or videos directly. It handles the common image formats and picks up frame sequences that follow standard naming conventions.

Example: blender -a //renders/frame_####.png

This opens a window displaying the image sequence. The player detects the frame range from the files matching the pattern.

Key sub-options:
- -p <sx> <sy>: Playback window position on screen. Coordinates are in pixels from the top-left corner of your primary display.
  
  Example: blender -a -p 100 200 //renders/frame_####.png (positions the player window 100 pixels from left, 200 from top)
- -f <fps> <fps_base>: Specify playback frame rate as a fraction. Default is 24 FPS (24/1).
  
  Example: blender -a -f 30 1 //renders/frame_####.png (plays at 30 FPS)
  
  Example: blender -a -f 24 1.001 //renders/frame_####.png (plays at 23.976 FPS, common for video)
- -s <frame> / -e <frame>: Start/End frame for playback, useful for previewing specific portions of longer animations.
  
  Example: blender -a -s 100 -e 200 //renders/complete_sequence_####.png (only plays frames 100-200)
- Multiple sequences can be played back in succession by listing them:
  
  Example: blender -a //shot1_####.png //shot2_####.png //shot3_####.png

4. Window and startup options

These control how Blender (potentially the GUI) starts up.

--factory-startup Skip reading the user's startup.blend and userpref.blend. Useful for ensuring a clean environment for scripts or troubleshooting.

Example: blender --factory-startup -b my_scene.blend -P my_script.py
--open-last Open the most recently opened blend file.
-w or --window-border: Force window with borders.
-W or --window-fullscreen: Force full-screen mode.
-p <sx> <sy> <w> <h> or --window-geometry <sx> <sy> <w> <h>: Set window position and size.
-M or --window-maximized: Force opening maximized.
-con or --start-console (Windows only): Start with the console window open.

5. Logging and debugging

Useful for diagnosing issues.

-d or --debug Enable general debugging mode. This enables memory error detection, disables mouse grab (useful for debuggers), and keeps Python's sys.stdin.
--log <match> Enable specific logging categories. Supports wildcards (*, ^).

Example: blender --log "wm.operator.*" to log window manager operator messages.

Example: blender --log "*undo*" to log all messages related to undo.
--log-level <level> Set logging verbosity (higher for more details, -1 for all).
--log-file <filepath> Output logs to a specified file.

The manual lists many specific debug flags like --debug-cycles or --debug-python.

6. Miscellaneous

-v or --version Print Blender version and exit.
-h or --help Print the command-line help text and exit.
-r or --register (Windows & Linux) Register .blend file extension for the current user.
--app-template <template> Set the application template to use.

Example: blender --app-template "Video Editing"
-noaudio / -setaudio <device> Control the audio system.

Error handling and troubleshooting

Something will go wrong. Here's how to approach the common cases:

Read the error message: Blender's console messages are usually specific enough to point at the cause.
- Cannot open file: ...: Check if the .blend file path is correct and if the file exists.
- Error: ... is not a .blend file: Ensure you're pointing to a valid Blender file.
- Python script fail, look in the console for now...: This indicates an error within your Python script. Blender will print a traceback in the console.
- Unknown arguments: blender -ba test.blend will exit because -ba is not a recognized combined argument. Arguments must be separated by spaces.
Check argument order: if a render isn't saving to the output you specified, or isn't using the settings you set, this is almost always why.
Verify paths: typos are common, and relative paths (//) resolve against the .blend file's location, not your working directory.
Python script errors (tracebacks):
- When a Python script fails, Blender prints a traceback. This shows the sequence of calls that led to the error and the error type (e.g., NameError, TypeError, FileNotFoundError).
- Look at the last few lines of the traceback to pinpoint the problematic line in your script and the nature of the error.
- Use print() statements in your script to debug values and flow, and run Blender with the console visible or log output to a file.
- The --python-exit-code <code> argument can be useful to make Blender exit with a specific code if a Python script fails, which helps in automated pipelines.
Use debug flags:
- Start with a general -d or --debug.
- If you suspect a specific area (e.g., Cycles, FFmpeg), use more targeted debug flags like --debug-cycles or --debug-ffmpeg. The output is verbose, but it tells you what Blender actually did.
Logging:
- --log "*" and --log-level -1 will provide maximum logging information.
- Use --log-file <filepath> to save extensive logs for later analysis, especially for background processes.
Factory startup for scripts: if a script behaves unexpectedly, run it with --factory-startup to rule out interference from user preferences or other add-ons. blender --factory-startup -b scene.blend -P script.py
Permissions: Blender needs read/write access to every directory it touches, including render output directories and script locations.
Check the console window: on Windows, use -con or launch blender_debug_log.cmd from Blender's installation directory to keep the console window open. On macOS and Linux, messages appear in the terminal you launched from.

Environment variables

Blender's behavior can also be influenced by environment variables. These are particularly useful for configuring paths without modifying command-line arguments every time. Some key ones include:

$BLENDER_USER_SCRIPTS: Directory for user scripts (add-ons, modules).
$BLENDER_USER_DATAFILES: Directory for user data files (icons, translations).
$BLENDER_SYSTEM_SCRIPTS: Directory for additional system-wide scripts.
$TMPDIR (Unix-like) / $TEMP (Windows): Directory for temporary files.
$OCIO: Path to override the OpenColorIO configuration file.

You can find a more comprehensive list in the blender -h output or the Blender's Directory Layout section of the manual.

Practical tips for the Blender CLI

Start simple. Get a basic render command working before you wrap it in a script.
Quote your paths. If a path or argument contains spaces, quote it: blender -b "my scene with spaces.blend".
Use --factory-startup when testing. It stops your own preferences from explaining a result you'll later fail to reproduce.
Develop scripts in the GUI first. Blender's Text Editor and Python Console give you immediate feedback; the CLI gives you a traceback after the fact.
Redirect output on long jobs. blender -b scene.blend -a > render_log.txt 2> error_log.txt (syntax varies slightly between shells).
Read the manual. The Blender Manual documents every argument and sub-command.

Conclusion

Most of the CLI is not complicated. The syntax is short, the flags are documented, and blender -h lists everything this article left out. What trips people up is argument order and path resolution, which is why both get their own sections above.

If you take one thing away: build the command incrementally, run it once, and read the console output before you script around it.

Mastering the Blender Command Line Interface (CLI): The Ultimate Guide to Automation and Headless Operations