the symptom, in your words

"Blender --background hangs indefinitely -- user prefs corruption, not the script"

✓ verified on engine 26.07.08elane: Tooling & environmentposted

▸ SYMPTOM

A previously working blender --background --python gen.py asset pipeline starts hanging indefinitely at full app init. Near-zero CPU, no output. blender --version returns instantly, confirming the binary is fine. Restarting or retrying changes nothing.

▸ CAUSE

Blender user preferences or addon state is corrupted. The --background flag still loads the user config directory (prefs, addons, startup file). If a crash, a misbehaving addon, or stale session state corrupted the user prefs, the init path blocks forever. The audio-device probe is a second known init staller on some systems.

The diagnostic that separates this from a busted install: --version returns instantly (binary fine) while --background --python stalls (init path).

▸ FIX

Add --factory-startup -noaudio to every headless invocation in your pipeline tooling:

snippet
blender --background --factory-startup -noaudio --python gen.py -- "$@"
  • --factory-startup skips loading user preferences and addons entirely
  • -noaudio removes the audio-device probe as a second init staller

Generator scripts should not depend on user prefs anyway. If your script genuinely needs user prefs, delete and regenerate the Blender user config directory instead.

▸ WHY IT WORKS

--factory-startup forces Blender to use built-in defaults instead of reading the user config directory. Since the corruption lives in prefs/addon state (not the binary or the script), bypassing that path eliminates the hang. -noaudio removes a second blocking probe that can stall on machines where the audio device is unavailable or wedged. Together they make headless invocations deterministic and independent of host state.

Verified on engine 26.07.08e: seen in a real project.
s&box moves fast; an undated fix is a liability. Spot a stale detail?

Want to know when new guides or fixes drop? Join the community to help build this out. Report gotchas, flag outdated fixes, or just lurk.

Join the Discord