Today I decided to roll up my sleeves and figure out how to run Blender headless. I’ve been telling people that it’s possible (based on documentation), but haven’t tried it out myself.
It’s actually pretty simple. Here are some steps. I’m on a Mac, so the paths might be slightly different if you’re on another operating system (check out these instructions for for Windows).
1. Figure out the path of the Blender executable. If you’ve ran the Blender console window before, it’s the same executable.
To find it via GUI, open up where the downloaded Blender zip was extracted.
On a Mac, show package contents and navigate to the blender executable.
(I currently have the extracted Blender 2.74 package on the Desktop for simplicity so my path reflects that.)
2. Run the executable with the -b argument to run Blender without the GUI. You can add the path to your PATH or run ./blender.
With path added:
3. You can pass scripts into Blender while running Blender headless.
blender -b -P /Users/Jenny/Desktop/my_script.py
4. Passing arguments into your script is a little bizarre. The documentation specifies the
-- (double dash) syntax to signal to Blender to stop reading those arguments and have them processed by your script. However, inside your script, if you’re trying to parse out the arguments, you get all the arguments, not just the ones after the
--. You must parse them out yourself. Here’s an example below. I’m using
argparse instead of
argparse is very powerful and handles a lot of edge cases (plus it’s just darn good practice).
blender -b -P /Users/Jenny/Desktop/my_script.py -- --number 5 --save '/Users/Jenny/Desktop/cube.obj'
The example script creates a number of cubes and exports them.
parser = argparse.ArgumentParser()
# get all script args
_, all_arguments = parser.parse_known_args()
double_dash_index = all_arguments.index('--')
script_args = all_arguments[double_dash_index + 1: ]
# add parser rules
parser.add_argument('-n', '--number', help="number of cubes")
parser.add_argument('-m', '--save', help="output file")
parsed_script_args, _ = parser.parse_known_args(script_args)
args = get_args()
number_of_cubes = int(args.number)
# create cubes
if number_of_cubes > 1:
for x in range(0, number_of_cubes):
bpy.ops.mesh.primitive_cube_add(location=(x, 0, 0))
# export scene
Running the script will give you an exported OBJ with the cubes.
There you have it: how to run headless Blender. Most people use headless Blender to farm out rendering jobs and increase render speeds, but you can do all sorts of neat stuffs by providing a script. Have fun!