---
title: "Blender headless: background render and Python scripts"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/blender-headless.md
upstream_source: https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
source_license: "Blender manual (CC-BY-SA); restated, not copied"
license_note: "Steps are our own words from the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-10-31
date: 2026-10-31
status: published
category: agent-howto
tags: agent-howto, blender, headless, render, python
checked_on: 2026-10-31
tested_version: untested
sources:
  - id: S1
    title: "Command Line Arguments (Blender manual source)"
    publisher: Blender Foundation
    url: https://projects.blender.org/blender/blender-manual/raw/branch/main/manual/advanced/command_line/arguments.rst
    accessed: 2026-10-31
    license: "CC-BY-SA, restated"
  - id: S2
    title: "Command Line Arguments (manual HTML, Wayback 2025-10-17; Blender 4.5 LTS)"
    publisher: Blender Foundation
    url: https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html
    accessed: 2026-10-31
    license: "CC-BY-SA, restated"
---
# Blender headless: background render and Python scripts

> **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