How to Write a Python Add-on for Blender: Your First Operator

What you’ll learn in this guide

This guide walks through turning a simple Python script in Blender into an operator and then an installable add-on. The example tool adds 1.0 to the X location of every object in the active scene. The goal isn’t to use this operation in every architectural project; it’s to show the building blocks of tool development in Blender, how to save the code, and how to run it from the user interface.

We’ll also cover some options for starting a background render from the command line. Add-on development and rendering are separate workflows; what they have in common is that they turn repetitive tasks into specific, trackable steps. It’s a good idea to test the operations shown here on a copy of your project file before using them on an important project.

Requirements

You should know the basics of using Blender and how to run a script in the Text Editor. Blender’s add-on guide also assumes familiarity with basic Python data types, modules, and classes. Running Blender from a terminal is another method recommended in the official guide for inspecting error messages more effectively.

The (2, 80, 0) value in the bl_info dictionary in the add-on example below specifies the minimum Blender version required to run the add-on. It doesn’t mean the add-on is automatically compatible with newer versions; the code needs to be tested in the version where it will be used. The command-line documentation is in the Blender 5.2 LTS manual.

Create your first add-on step by step

1. In Blender’s Text Editor, create a new text block and add the code below. It defines an operator named ObjectMoveX. When run, the operator loops through the objects in the active scene and increases each object’s X location by 1.0. The UNDO option enables undo support for the operator.

bl_info = {
    'name': 'Move X Axis',
    'blender': (2, 80, 0),
    'category': 'Object',
}

import bpy

class ObjectMoveX(bpy.types.Operator):
    """Move every scene object along the X axis."""
    bl_idname = 'object.move_x'
    bl_label = 'Move X by One'
    bl_options = {'REGISTER', 'UNDO'}

    def execute(self, context):
        scene = context.scene
        for obj in scene.objects:
            obj.location.x += 1.0
        return {'FINISHED'}

def register():
    bpy.utils.register_class(ObjectMoveX)

def unregister():
    bpy.utils.unregister_class(ObjectMoveX)

if __name__ == '__main__':
    register()

bl_info provides Blender with information such as the add-on’s name and category; the version field in the example specifies the minimum requirement. execute() contains the operation to perform when the operator runs. Here, the scene context is obtained through the context argument passed to the function. The official guide recommends using this parameter in operators whenever possible.

1. Click Run Script in the Text Editor to run the code. At this stage, the operator is registered; the objects haven’t been moved yet. Open the Operator Search menu, search for Move X by One, and press Enter. In the guide’s example, this display name is defined in the bl_label field.

2. To install the script as an add-on, save it as a .py file with a name that follows Python module naming rules. In Blender, go to Preferences > Add-ons > Install… and select the file. When the add-on appears in the list, enable it. To keep it enabled after restarting, use the Save as Default option, as described in the guide.

When the add-on is enabled, Blender calls register(); when it’s disabled, Blender calls unregister(). In this code, those functions register and unregister the operator class. Running a script directly is a quick way to test it during development; installing the add-on lets Blender manage it in the add-on list in Preferences.

Use in architectural and visualization workflows

The example operator affects every object in the active scene. So, when you run it directly in an architectural scene, it’s important to know which objects will move. If you’re developing a tool for use in an office, define its scope to suit the project structure and test it in a sample scene first. This example is a starting exercise that explains operator logic, not a ready-made architectural distribution tool.

A second example in Blender’s add-on guide places linked duplicates of the active object between the 3D cursor and the object. The duplicates are linked to the scene collection, and their positions are calculated based on the relationship between the object and the cursor. In the first version, the total number of duplicates is fixed at 10. The example explains how to build tools for repeated elements and shows that settings can also be made user-adjustable.

To render from the command line, run Blender in background mode with the -b or --background option. The Cycles example in the official documentation selects a specific frame and device as follows:

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

This command renders frame 20 and selects the OPTIX device. The guide lists CPU, CUDA, OPTIX, HIP, ONEAPI, and METAL as valid Cycles device options. The selected device must be compatible with the system you’re using.

The documentation also includes a separate command example for outputting animation frames as PNGs:

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

In this command, -o specifies the output path, -F the file format, -x whether to add the extension, and -a to render the animation frames. A path starting with // is interpreted relative to the .blend file. If you use # characters in the filename, they act as placeholders for the frame number. The two examples cover different needs; adjust options such as frame, file format, output location, and device to suit the render you want.

This approach can help Blender users who want to automate repetitive scene operations, as well as teams planning to render outside the interface. However, the sources don’t specify any particular hardware requirements or licensing costs. For add-ons, check compatibility with the Blender version; for rendering, check the selected device and define output settings explicitly.

Common mistakes and next steps

• Don’t treat running the script and running the operator as the same step. In the example, the first action registers the operator; you must run the operator separately to change the scene.

• Check the operator’s scope. In the example, the X location of every object in the active scene changes.

• Read the (2, 80, 0) value in bl_info as the minimum version requirement; don’t treat it as a compatibility guarantee for newer Blender versions.

• For background rendering, specify the file path, output format, frame range, and Cycles device as needed. The example commands may include settings that aren’t present in the other example.

As a next step, you can explore the bpy.context and bpy.types.Operator sections in the Blender API documentation. The official add-on guide also covers turning fixed values into user-adjustable operator properties. As a tool grows, making settings such as the number of duplicates adjustable can help accommodate different scene requirements.

Sources and license

This guide was adapted from Blender Manual’s “Add-on Tutorial” and “Command Line Arguments” documentation. Both sources are published under the CC BY-SA 4.0 license; this content has been adapted into English in accordance with those license terms.