BLENDER(1)

💖 BLENDER 💖

blender — a full-featured 3D application, bestie. Like, the whole thing. It lives in the General Commands Manual section, iykyk.

---

✨ NAME ✨

blender — a full-featured 3D application 🎀

---

🦋 SYNOPSIS 🦋

blender [args ...] [file] [args ...]

---

🌸 DESCRIPTION 🌸

okay so. blender is a full-featured 3D application and it is genuinely not playing around. It supports the entirety of the 3D pipeline — like the way that it does all of this:

• modeling
• rigging
• animation
• simulation
• rendering
• compositing
• motion tracking
• video editing

and it does it all in one place. main character energy, no cap. 💅

Use Blender to create 3D images and animations, films and commercials, content for games, architectural and industrial visualizations, and scientific visualizations. Versatile queen. 👑

https://www.blender.org

---

💅 OPTIONS 💅

Usage:

blender [args ...] [file] [args ...]

---

🎬 Render Options 🎬

• -b, --background — Run in background (often used for UI-less rendering).

heads up bestie: the audio device is disabled in background-mode by default 💀 and it can be re-enabled by passing in '-setaudio Default' afterwards.

• -a, --render-anim — Render frames from start to end (inclusive).
• -S, --scene <name> — Set the active scene <name> for rendering.
• -f, --render-frame <frame> — Render frame <frame> and save it.
  • +<frame> start frame relative, -<frame> end frame relative.
  • A comma separated list of frames can also be used (no spaces).
  • A range of frames can be expressed using '..' separator between the first and last frames (inclusive).
• -s, --frame-start <frame> — Set start to frame <frame>, supports +/- for relative frames too.
• -e, --frame-end <frame> — Set end to frame <frame>, supports +/- for relative frames too.
• -j, --frame-jump <frames> — Set number of frames to step forward after each rendered frame.
• -o, --render-output <path> — Set the render path and file name.

Use '//' at the start of the path to render relative to the blend-file.

You can use path templating features such as '{blend_name}' in the path. See Blender's documentation on path templates for more details.

The '#' characters are replaced by the frame number, and used to define zero padding.

• 'animation_##_test.png' becomes 'animation_01_test.png'
• 'test-######.png' becomes 'test-000001.png'

When the filename does not contain '#', the suffix '####' is added to the filename.

The frame number will be added at the end of the filename, eg:

# blender -b animation.blend -o //render_ -F PNG -x 1 -a

'//render_' becomes '//render_####', writing frames as '//render_0001.png'

• -E, --engine <engine> — Specify the render engine. Use '-E help' to list available engines. 🔍
• -t, --threads <threads> — Use amount of <threads> for rendering and other operations [1-1024], 0 to use the system's processor count.

---

🌀 Cycles Render Options 🌀

lowkey important: Cycles add-on options must be specified following a double dash.

• --cycles-device <device> — Set the device used for rendering.

Valid options are: 'CPU' 'CUDA' 'OPTIX' 'HIP' 'ONEAPI' 'METAL'.

Append +CPU to a GPU device to render on both CPU and GPU.

Example:

# blender -b file.blend -f 20 -- --cycles-device OPTIX

• --cycles-print-stats — Log statistics about render memory and time usage. 📊

---

🎨 Format Options 🎨

• -F, --render-format <format> — Set the render format.

Valid options are: 'TGA' 'RAWTGA' 'JPEG' 'IRIS' 'PNG' 'BMP' 'HDR' 'TIFF'.

Formats that can be compiled into Blender, not available on all systems: 'OPEN_EXR' 'OPEN_EXR_MULTILAYER' 'FFMPEG' 'CINEON' 'DPX' 'JP2' 'WEBP'.

• -x, --use-extension <bool> — Set option to add the file extension to the end of the file.

---

🎞️ Animation Playback Options 🎞️

• -a <options> <file(s)> — Instead of showing Blender's user interface, this runs Blender as an animation player, to view movies and image sequences rendered in Blender (ignored if '-b' is set).

Playback Arguments:

• -p <sx> <sy> — Open with lower left corner at <sx>, <sy>.
• -m — Read from disk (Do not buffer).
• -f <fps> <fps_base> — Specify FPS to start with.
• -j <frame> — Set frame step to <frame>.
• -s <frame> — Play from <frame>.
• -e <frame> — Play until <frame>.
• -c <cache_memory> — Amount of memory in megabytes to allow for caching images during playback. Zero disables (clamping to a fixed number of frames instead).

---

🪟 Window Options 🪟

• -w, --window-border — Force opening with borders, in a normal (non maximized) state.
• -M, --window-maximized — Force opening maximized.
• -W, --window-fullscreen — Force opening full-screen.
• -p, --window-geometry <sx> <sy> <w> <h> — Open with lower left corner at <sx>, <sy> and width and height as <w>, <h>.
• -con, --start-console — Start with the console window open (ignored if '-b' is set), (Windows only). 🪟
• --no-native-pixels — Do not use native pixel size, for high resolution displays (MacBook 'Retina').
• --no-window-frame — Disable all window decorations (Linux only).
• --no-window-focus — Open behind other windows and without taking focus. 🙈

---

🐍 Python Options 🐍

• -y, --enable-autoexec — Enable automatic Python script execution.
• -Y, --disable-autoexec — Disable automatic Python script execution (Python-drivers & startup scripts), (default).
• -P, --python <filepath> — Run the given Python script file.
• --python-text <name> — Run the given Python script text block.
• --python-expr <expression> — Run the given expression as a Python script.

The expression may be a complete multi-line script; you are limited only by the platform's maximum argument length.

• --python-console — Run Blender with an interactive console.
• --python-exit-code <code> — Set the exit-code in [0..255] to exit if a Python exception is raised (only for scripts executed from the command line), zero disables.
• --python-use-system-env — Allow Python to use system environment variables such as 'PYTHONPATH'. This also enables user environment, see: '--python-use-user-env'.
• --python-use-user-env — Allow Python to use user's site-packages directory. This disables full isolation for the Python environment.
• --addons <addon(s)> — Comma separated list (no spaces) of add-ons to enable in addition to any default add-ons. 🧩

---

🌐 Network Options 🌐

• --online-mode — Allow internet access, overriding the preference.
• --offline-mode — Disallow internet access, overriding the preference.

---

📜 Logging Options 📜

• --log <match> — Enable logging categories, taking a single comma separated argument.
  • --log "*": log everything
  • --log "event": logs every category starting with 'event'.
  • --log "render,cycles": log both render and cycles messages.
  • --log "*mesh*": log every category containing 'mesh' sub-string.
  • --log "*,^operator": log everything except operators, with '^prefix' to exclude.
• --log-level <level> — Set the logging verbosity level.
  • fatal: Fatal errors only
  • error: Errors only
  • warning: Warnings
  • info: Information about devices, files, configuration, operations
  • debug: Verbose messages for developers
  • trace: Very verbose code execution tracing
• --log-show-memory — Show memory usage for each log message.
• --log-show-source — Show source file and function name in output.
• --log-show-backtrace — Show a back trace for each log message (debug builds only).
• --log-file <filepath> — Set a file to output the log to.
• --log-list-categories — List all available logging categories for '--log', and exit.

---

🐛 Debug Options 🐛

• -d, --debug — Turn debugging on. 🔍
  • Enables memory error detection
  • Disables mouse grab (to interact with a debugger in some cases)
  • Keeps Python's 'sys.stdin' rather than setting it to None
• --debug-value <value> — Set debug value of <value> on startup.
• --debug-events — Enable debug messages for the event system.
• --debug-handlers — Enable debug messages for event handling.
• --debug-libmv — Enable debug messages from libmv library.
• --debug-memory — Enable fully guarded memory allocation and debugging.
• --debug-jobs — Enable time profiling for background jobs.
• --debug-python — Enable debug messages for Python.
• --debug-depsgraph — Enable all debug messages from dependency graph.
• --debug-depsgraph-eval — Enable debug messages from dependency graph related on evaluation.
• --debug-depsgraph-build — Enable debug messages from dependency graph related on graph construction.
• --debug-depsgraph-tag — Enable debug messages from dependency graph related on tagging.
• --debug-depsgraph-no-threads — Switch dependency graph to a single threaded evaluation.
• --debug-depsgraph-time — Enable debug messages from dependency graph related on timing.
• --debug-depsgraph-pretty — Enable colors for dependency graph debug messages. 🌈
• --debug-depsgraph-uid — Verify validity of session-wide identifiers assigned to ID data-blocks.
• --debug-ghost — Enable debug messages for Ghost (Linux only). 👻
• --debug-wintab — Enable debug messages for Wintab.
• --debug-gpu — Enable GPU debug context and information for OpenGL 4.3+.
• --debug-gpu-force-workarounds — Enable workarounds for typical GPU issues and disable all GPU extensions.
• --debug-gpu-compile-shaders — Compile all statically defined shaders to test platform compatibility.
• --debug-gpu-shader-debug-info — Enable shader debug info generation (Vulkan only).
• --debug-gpu-scope-capture — Capture the GPU commands issued inside the given scope name.
• --debug-gpu-shader-source — Save the compiled GPU shader source code for the given shader name. The given name can contain leading or trailing wildcard "*" to match multiple shaders. Files are saved in the current working directory inside a directory named "Shaders".

---

…and that's literally just part one bestie, don't go anywhere 💖

• --debug-gpu-shader-no-preprocessor — skips the preprocessor pass and just lets the driver or shader compiler do the preprocessing instead. bonus: it also turns off dead code elimination. two for one bestie 💅
• --debug-gpu-shader-no-dce — skips the dead code elimination pass. that's it, that's the whole vibe.
• --debug-gpu-no-texture-pool — turns off memory aliasing optimizations inside the GPU texture pool.
• --debug-gpu-vulkan-local-read — forces Vulkan dynamic rendering local read, but only when the device actually supports it. no cap.
• --debug-wm — turns on debug messages for the window manager. it also shows all operators in search and surfaces keymap errors. very "let me see everything" energy 🔍
• --debug-xr — debug messages for virtual reality contexts. this one enables the OpenXR API validation layer, (OpenXR) debug messages, and general info prints. the whole XR gossip pipeline ✨
• --debug-xr-time — debug messages for virtual reality frame rendering times. clocking the frames, fr fr ⏱️
• --debug-all — enables all debug messages. go big or go home, no in-between.
• --debug-io — debug messages for I/O.
• --debug-fpe — enables floating-point exceptions.
• --debug-exit-on-error — bails immediately the second internal errors get detected. dramatic exit, but make it functional 💀
• --debug-freestyle — debug messages for Freestyle.
• --console-crash-handler — uses the console to report crashes.
• --disable-crash-handler — disables the crash handler.
• --disable-abort-handler — disables the abort handler.
• --verbose <verbose> — sets the logging verbosity level, for the debug messages that support it.
• -q or --quiet — suppresses status printing. warnings & errors are still printed, so it's not a full muzzle, bestie 🙈

---

🎮 GPU Options

• --gpu-backend — forces a specific GPU backend. the valid options are: 'opengl' or 'vulkan'. pick your fighter.
• --gpu-device <device> — picks a specific GPU device, overriding the GPU device from user preferences for this run only. accepted forms, bestie, listen up:
  • '<vendor-hex>/<device-hex>/<index-hex>' — matches the identifier used in user preferences, with vendor PCI ID, device PCI ID and enumeration index all hex-encoded.
  • '<index>' — no slashes at all, just picks the Nth supported device by enumeration order, decimal.
  • 'help' — prints supported Vulkan devices and exits. the little helper icon 🫶

Only used with the Vulkan backend. other backends print a warning and ignore this option entirely. if the requested Vulkan device is unavailable, Blender falls back to the saved GPU preference — unless --gpu-device-no-fallback is also set.

• --gpu-device-no-fallback — fail instead of falling back when --gpu-device doesn't match a usable Vulkan device. no backup plan, no plan B 💀
• --gpu-vsync — sets the VSync. valid options are: 'on', 'off' & 'auto' for adaptive sync.
  • the default settings depend on the GPU driver.
  • disabling VSync can be useful for testing performance.
  • 'auto' is only supported by the OpenGL backend.
• --gpu-compilation-subprocesses — overrides the Max Compilation Subprocesses setting (OpenGL only).
• --profile-gpu — enables CPU & GPU performance profiling for GPU debug groups. it outputs a profile.json file in the Trace Event Format to the current directory. data girlies, rise 📊

---

🍓 Misc Options

• --open-last — opens the most recently opened blend file instead of the default startup file. it's giving "resume where I left off" ✨
• --app-template <template> — sets the application template (matching the directory name). use 'default' for none.
• -X or --factory-startup — skips reading the 'startup.blend' in the user's home directory. fresh slate, zero baggage 💅
• --enable-event-simulate — enables the event simulation testing feature 'bpy.types.Window.event_simulate'.
• --env-system-datafiles — sets the BLENDER_SYSTEM_DATAFILES environment variable.
• --env-system-scripts — sets the BLENDER_SYSTEM_SCRIPTS environment variable.
• --env-system-extensions — sets the BLENDER_SYSTEM_EXTENSIONS environment variable.
• --env-system-python — sets the BLENDER_SYSTEM_PYTHON environment variable.
• -noaudio — forces the sound system to None. silence, but make it a choice 🔇
• -setaudio — forces the sound system to a specific device. the options are 'None' 'Default' 'SDL' 'OpenAL' 'CoreAudio' 'JACK' 'PulseAudio' 'WASAPI'.
• -c or --command <command> — runs a command which consumes all remaining arguments. use '-c help' to list all the other commands. pass '--help' after the command to see its help text.

this implies '--background' mode. heads up bestie.

• -h or --help — prints this help text and exits. the classic.
• /? — prints this help text and exits (Windows only).
• -r or --register — registers the blend-file extension for the current user, then exits (Windows & Linux only).
• --register-allusers — registers the blend-file extension for all users, then exits (Windows & Linux only).
• --unregister — unregisters the blend-file extension for the current user, then exits (Windows & Linux only).
• --unregister-allusers — unregisters the blend-file extension for all users, then exits (Windows & Linux only).
• --qos <level> — sets the Quality of Service (QoS) mode for hybrid CPU architectures (Windows only).
  • default: uses the default behavior of the OS.
  • high: always makes use of performance cores. main character cores only 🔥
  • eco: schedules Blender threads exclusively to efficiency cores. low-power era.
• -v or --version — prints Blender version and exits.
• -- — ends option processing, and the following arguments are passed unchanged. access them via Python's 'sys.argv'. periodt.

---

🌈 Other Options

• --disable-depsgraph-on-file-load — background mode only: doesn't systematically build and evaluate ViewLayers' dependency graphs when loading a blend-file in background mode (that's the '-b' or '-c' options).

Scripts that need evaluated data then have to explicitly ensure an evaluated depsgraph is available, like by calling depsgraph = context.evaluated_depsgraph_get().

NOTE: this is a temporary option. in the future, depsgraph will never be automatically generated on file load in background mode. so don't get attached, bestie 😭

• --disable-liboverride-auto-resync — doesn't perform library override automatic resync when loading a new blend-file.

NOTE: this is an alternative way to get the same effect as when setting the 'No Override Auto Resync' User Preferences Debug option.

• --debug-ffmpeg — enables debug messages from FFmpeg video input and output.
• --debug-cycles — enables debug messages from Cycles.

---

🧚 Argument Parsing

Arguments must be separated by white space, eg:

# blender -ba test.blend

...will exit since '-ba' is an unknown argument. yeah, no skipping the space, sorry babe 🙈

---

🦋 Argument Order

Arguments are executed in the order they are given. eg:

# blender --background test.blend --render-frame 1 --render-output "/tmp"

...will not render to '/tmp' because '--render-frame 1' renders before the output path is set. order matters, always 💀

# blender --background --render-output /tmp test.blend --render-frame 1

...will not render to '/tmp' because loading the blend-file overwrites the render output that was set.

# blender --background test.blend --render-output /tmp --render-frame 1

...works as expected. slay. this is the one. 👑

---

🌸 ENVIRONMENT VARIABLES

• $BLENDER_USER_RESOURCES — replace default directory of all user files. other 'BLENDER_USER_*' variables override when set.
• $BLENDER_USER_CONFIG — directory for user configuration files.
• $BLENDER_USER_SCRIPTS — directory for user scripts.
• $BLENDER_USER_EXTENSIONS — directory for user extensions.
• $BLENDER_USER_DATAFILES — directory for user data files (icons, translations, ..).
• $BLENDER_SYSTEM_RESOURCES — replace default directory of all bundled resource files.
• $BLENDER_SYSTEM_SCRIPTS — directories to add extra scripts.
• $BLENDER_SYSTEM_EXTENSIONS — directory for system extensions repository.
• $BLENDER_SYSTEM_DATAFILES — directory to replace bundled datafiles.
• $BLENDER_SYSTEM_PYTHON — directory to replace bundled Python libraries.
• $BLENDER_CUSTOM_SPLASH — full path to an image that replaces the splash screen.
• $BLENDER_CUSTOM_SPLASH_BANNER — full path to an image to overlay on the splash screen.
• $BLENDER_OCIO — path to override the OpenColorIO configuration file. if not set, the 'OCIO' environment variable is used.
• $SPNAV_SOCKET — the socket path to connect to the 3D-mouse daemon (Unix only).
• $TMPDIR — store temporary files here (UNIX Systems). the path must reference an existing directory or it will be ignored. it's giving "we'll just pretend you didn't say that" 🫶

---

👀 SEE ALSO

• luxrender(1)

---

💜 AUTHORS

This manpage was written for a Debian GNU/Linux system by Daniel Mester <mester@uni-bremen.de> and updated by Cyril Brulebois <cyril.brulebois@enst-bretagne.fr> and Dan Eicher <dan@trollwerks.org>. absolute legends, we stan ✨

---

okay bestie that's the whole page — every last flag, path and env var accounted for, nothing skipped, no notes. this one came from Blender 5.2.2 LTS, dated October 07, 2026. go forth and render something iconic 💖🎀🦋