Blender Python Automation: Turning Repeated Work into Scripts

Based on: the official Blender 5.2 LTS Python API documentation and manual (English interface, default keymap)

Almost every setting you can change with a button in Blender can also be changed with Python code. So jobs that mean repeating the same clicks dozens of times, such as lining up 50 objects, matching render settings across several files, or running renders overnight, can be handed to a short script (a text that lists commands). It is written so that you can follow along even if you have never programmed.

By the end of this guide you will be able to:

1. Find where to run scripts.
2. Tell apart the three pillars of Blender Python (bpy.data, bpy.context, bpy.ops).
3. Copy and run three short examples as they are.

Scripts: a cooking recipe

Working by hand is like cooking from memory every time. A script writes that process down on a recipe card. Once it is written, Blender follows the steps exactly, as many times as you like, without mistakes. Change only the amounts (the numbers) and you can easily get a different result.

A few of the things scripts can do:

• Edit any data the interface can (scenes, meshes, particles, and so on)
• Run tools with your own settings
• Create interface elements such as menus and panels
• Create new tools

This guide focuses on the first two, that is, running features that already exist automatically.

Getting ready: turn on and open three things

1. Open the Scripting workspace: Click Scripting in the tabs at the top of the screen. The Text Editor, where you write code, and the Python Console, where you try one line at a time, open together. There is no need to arrange your own layout; just use this workspace.
2. Turn on Python Tooltips: In Edit ‣ Preferences ‣ Interface, turn on Developer Extras and Python Tooltips. Now when you hover over a button, the Python name of that setting is shown too. Blender itself answers the question "what is this button called in code?"
3. Watch the Info editor: When you use a tool, the Info editor logs the action as a Python command. Not every action is logged, only some tools (Blender calls them "operators"). Even so, it is a good hint when you write code for the first time.

There are two places to run a script.

The Text Editor's Templates menu contains many official example scripts that are useful for reference.

The three pillars of Blender Python: data, context, ops

Blender's Python module is called bpy. At first you only need to know these three.

To continue the recipe comparison: a kitchen has a pantry, the ingredients you have put on the cutting board right now, and cooking tools such as knives and pots.

Knowing these rules as well will save you some errors.

• Items in bpy.data can be taken out by name (["Cube"]) or by index ([0]), but the index can change while you work. Using the name is safer.
• New data is created with new() on a collection such as bpy.data.meshes (for example bpy.data.meshes.new("name")) and removed with remove() on the same collection.
• bpy.context is read-only. bpy.context.active_object = obj raises an error; to change the active object, use bpy.context.view_layer.objects.active = obj.
• Tools in bpy.ops only run in the right situation (mode, editor). If the conditions don't match, you get a "context is incorrect" error. When you see it, first check that the current mode (Object/Edit) and the editor under the mouse are right. To check ahead of time in code, add .poll() after the tool name. For example, bpy.ops.object.mode_set.poll() returns True if the mode can be changed now, and False if not.

Example 1: change resolution % with one line

Type the line below in the Python Console. In the Python Console, bpy is already imported, so you can use it without import bpy. Scripts run from the Text Editor, on the other hand, normally put import bpy on the first line, as in Example 2.

bpy.context.scene.render.resolution_percentage = 50

The Resolution % field in the Output tab of the Properties editor changes to 50 (with a new file's default 1920×1080, it renders at 960×540). render.resolution_percentage is the same name shown in the button's tooltip. What this setting does is explained in Render settings for beginners.

Example 2: line up five boxes and make them jump one after another

In the Text Editor, click New, paste the code below, and click Run Script.

import bpy

# If the default scene's big Cube exists, delete it first (so it doesn't overlap the new boxes)
if "Cube" in bpy.data.objects:
    bpy.data.objects.remove(bpy.data.objects["Cube"])

for i in range(5):
    bpy.ops.mesh.primitive_cube_add(size=1, location=(i * 2, 0, 0))
    cube = bpy.context.object          # the box just created
    cube.name = f"Box_{i}"
    start = 1 + i * 5                  # each box starts 5 frames later
    cube.keyframe_insert(data_path="location", frame=start)        # floor
    cube.location.z = 2                                            # 2 m up
    cube.keyframe_insert(data_path="location", frame=start + 10)   # top
    cube.location.z = 0                                            # back to the floor
    cube.keyframe_insert(data_path="location", frame=start + 20)   # landing

Line by line:

• if "Cube" in bpy.data.objects: deletes the big Cube that a new file starts with (2 m on each side, at the origin). Without this line, the first box is buried inside that Cube and you seem to have only four boxes.
• for i in range(5): repeats the lines below five times (i is 0, 1, 2, 3, 4).
• primitive_cube_add: the same tool as Add ‣ Mesh ‣ Cube in the menu. It places 1 m boxes 2 m apart.
• keyframe_insert(data_path="location", ...): the function that inserts keyframes. Here it keys location only (unlike pressing I in the viewport, which usually keys location, rotation, and scale together).
• Each box gets three keys: floor → 2 m up 10 frames later → back on the floor another 10 frames later.

Press Space to play. The boxes jump up once and come down, one after another from the left. The last box lands at frame 41, and after that everything stays on the floor until the end of playback (frame 250 by default). By hand you would repeat add, move, and key for every box; here you only change the number 5 to 50.

If you run the same script again, boxes with names like Box_0.001 appear on top of the old ones. Delete the boxes you made before running it again. Undo with Ctrl+Z, or hover over the 3D Viewport and press A (select all) → X → Delete. A also selects the camera and the light, so to keep them, select only the objects starting with Box_ in the Outliner and delete those. What keyframes and interpolation are is covered in Keyframe animation in Blender for beginners.

Example 3: apply preview settings in one go

Typing the same render settings every time you open a file can also be cut down with a script. Save the file below as preview_settings.py.

import bpy

render = bpy.context.scene.render
render.resolution_x = 1920
render.resolution_y = 1080
render.resolution_percentage = 50      # test at 960x540 (50% of 1920x1080)
render.fps = 30
render.filepath = "//preview/frame_"   # // = the folder the blend file is in

All of these setting names are in the official API's RenderSettings page. For the final render, raise only resolution_percentage to 100. The order of checking small and enlarging only the final is explained in Render settings for beginners.

There are two ways to use the saved preview_settings.py in another blend file. Open that file, load the script with Open in the Text Editor, and click Run Script, or run it with -P as in the command-line section just below.

Running without a window: command line and background rendering

Scripts can run without opening the Blender window. Type this in a terminal (a window where you type commands as text). If the terminal is new to you, read GUI vs CLI: what is the difference first.

blender -b scene.blend -P preview_settings.py -f 1

This is the basic form that only shows the shape of the command. On Windows the installer does not add Blender to the command search path (PATH), so typing just blender often gives a "not recognized" error. In that case, write the full path of the executable in place of blender.

Match the version number in the folder name (5.2) to the version you installed. If scene.blend and preview_settings.py are not in the folder the terminal is in, write their full paths too.

Test a single frame with -f 1 first. -a renders every frame from the start to the end of the scene, which is 250 images for a new file. When one frame comes out as you want, change -f 1 to -a. Also, settings changed with -P apply only to this run and are not saved to the blend file. To keep them in the file, open it in Blender, run the script, and save.

The thing to watch is the order. Arguments run in the order they are written. Open the file first, then run the settings script, and then render. If you put the settings before the file, opening the file overwrites them. If you leave this running at a time when you are not using the computer much, it won't get in the way of other work.

Using scripts safely

Python has no limit on what it can do. So run only scripts from sources you trust.

• Automatic execution of scripts inside blend files is off by default. If a prompt asks for permission to run scripts when you open a file and you don't know where the file came from, choose Ignore.
• Even if you turn on Auto Run Python Scripts in Preferences, you can exclude folders you can't trust, such as your downloads folder.
• Read code from the internet before running it, and test important files on a copy first.

Writing scripts with AI

You can also ask an AI for a first draft, such as "Blender Python code that places 10 boxes in a circle". Here too, the three pillars above and the official documentation are your reference. AI-written code may use an old API and fail, so look up function names in the official API documentation. Ways to let an AI control Blender directly continue in What is MCP and AI and Blender: Start Small and Work Together.

Summary

Further reading

• GUI vs CLI: what is the difference
• AI and Blender: Start Small and Work Together
• What is MCP: a USB-C-like standard for plugging tools into AI

References

• Blender Python API, Quickstart: https://docs.blender.org/api/5.2/info_quickstart.html
• Blender Python API, Tips and Tricks: https://docs.blender.org/api/5.2/info_tips_and_tricks.html
• Blender Python API, Operators (bpy.ops): https://docs.blender.org/api/5.2/bpy.ops.html
• Blender Python API, BlendDataObjects (objects.remove): https://docs.blender.org/api/5.2/bpy.types.BlendDataObjects.html
• Blender Python API, bpy_struct.keyframe_insert: https://docs.blender.org/api/5.2/bpy.types.bpy_struct.html
• Blender Python API, Mesh Operators: https://docs.blender.org/api/5.2/bpy.ops.mesh.html
• Blender Python API, RenderSettings: https://docs.blender.org/api/5.2/bpy.types.RenderSettings.html
• Blender Manual, Text Editor: https://docs.blender.org/manual/en/5.2/editors/text_editor.html
• Blender Manual, Python Console: https://docs.blender.org/manual/en/5.2/editors/python_console.html
• Blender Manual, Launching from the Command Line (Windows): https://docs.blender.org/manual/en/5.2/advanced/command_line/launch/windows.html
• Blender Manual, Launching from the Command Line (macOS): https://docs.blender.org/manual/en/5.2/advanced/command_line/launch/macos.html
• Blender Manual, Command Line Arguments: https://docs.blender.org/manual/en/5.2/advanced/command_line/arguments.html
• Blender Manual, Scripting & Security: https://docs.blender.org/manual/en/5.2/advanced/scripting/security.html