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

What will you learn in this guide?

In this guide, you’ll turn a simple Python script that runs in Blender into an operator and then a loadable add-on. The example tool moves every object in the active scene 1 unit along the X axis. The goal isn’t to provide a ready-to-use production tool, but to explain step by step how Blender defines, registers, and runs operators.

An add-on is a Python module with the extra information Blender needs to recognize and display it in its list. The bl_info dictionary specifies details such as the add-on’s name and category, as well as the minimum Blender version required. An operator makes an action callable from within Blender. In this example, we’ll run the action from the Operator Search window.

One important detail: the example affects every object in the active scene, not just selected objects. For that reason, it’s safer to run your first tests in a test scene or a copy of the file—not in an important project file.

Requirements

You’re expected to know the basics of using Blender and how to run a script in the Text Editor. Familiarity with basic Python types, such as numbers, Booleans, strings, lists, tuples, dictionaries, and sets, is also recommended. The guide also recommends having a basic understanding of Python modules and classes.

The add-on information in the guide’s example specifies Blender version (2, 80, 0). This is the minimum version stated in the example metadata; it does not mean the code has been tested with current Blender releases. You’ll need to verify API behavior in the version you use. No user account, hardware feature, or paid license is listed as a requirement.

Running Blender from a terminal is one option for debugging. The guide also notes that enabling Developer Extras in Preferences can support the add-on development process.

Step by step: write your first operator

1. Add the code to the Text Editor

In the example below, the ObjectMoveX class defines the operator. When execute() runs, it processes the active scene’s objects one by one and adds 1.0 to each object’s X location. The UNDO option in bl_options 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):
    """My Object Moving Script"""
    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()

This simple example registers the operator class; it doesn’t add a UI item to a menu. unregister() removes the registered class. bl_idname specifies the operator’s unique identifier, while bl_label sets the name displayed in Blender’s interface and search. When the operation succeeds, the execute() function returns FINISHED.

2. Run the script and call the operator

Paste the code into Blender’s Text Editor and run it. The script registers the operator; it doesn’t move the objects automatically at this point. Then open the Operator Search window, search for Move X by One, and run the operator. It moves every object in the active scene 1 unit along the X axis.

It’s important to use the context parameter in execute(self, context). Blender may run operators with a special context in some situations. For this reason, the guide recommends using the context value passed to the operator rather than referring directly to the global context.

3. Save the file and load it as an add-on

Save the script you tested to a file. Choose a filename that can be used as a Python module and add the .py extension. In Blender Preferences, open the add-on installation option in the Add-ons section, select the file, and enable the add-on from the list. If you want it to remain enabled after restarting, you can use the Save as Default option mentioned in the guide.

Enabling the add-on tells Blender to run the module and perform the registration steps in register(). When you disable the add-on, Blender calls the unregister() function; in this example, that removes the operator class. The source and destination folders may be shown in the console during installation. The guide also explains how to display add-on paths in the Python Console using addon_utils.paths().

Using it in architectural and visualization workflows

This example shows the basic idea of turning repetitive tasks into an operator in Blender, as technical artists and developers might do. In architectural scenes, a similar approach can be a starting point for building custom tools for clearly defined, repeatable tasks. However, this code is not an office tool ready for direct use in a production scene: it changes the location of every object in the active scene.

Use a copy of the scene for your first test, and check which objects the operator affects. Before sharing the add-on with your team, separately verify the target Blender version and the compatibility of the API elements it uses. The source doesn’t specify any hardware requirements, so it isn’t possible to draw hardware recommendations from it. License terms and version compatibility should also be evaluated before distribution.

Common mistakes

• Expecting objects to move as soon as you run the script: The first run registers the operator. To change the objects, select Move X by One from the Operator Search window.

• Overlooking the scope of the operation: The code isn’t limited to selected objects; it processes every object in the active scene.

• Forgetting the file format: Save the add-on file with the .py extension and choose a filename that can be used as a Python module.

• Confusing saving with enabling: Saving the file doesn’t enable the add-on by itself. You need to load the file from Preferences and enable it in the list.

Next steps

First, run the example in a test scene and observe the operator’s result. Then look at the roles of bl_info, the operator class, execute(), and the registration functions individually. As a next development step, you could explore turning fixed values into operator properties that users can adjust; the rest of the Blender guide covers this topic and another example that creates linked duplicates of objects.

If you encounter error messages, checking Blender’s console output can help you identify where the problem occurred. The Blender API Overview and the documentation for bpy.context and bpy.types.Operator are also among the reference resources cited by the guide for a closer look at the concepts used here.

Source and license

This guide has been adapted into Turkish based on the add-on and operator example in Blender’s official “Add-on Tutorial” document. The source is licensed under CC BY-SA 4.0.