Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Python Scripting

Blender Add-ons: Write Operators, Panels and Properties

Write your first Blender add-on: bl_info, a custom Operator, a UI Panel, scene properties, registration, keymaps and how to install and share it.

A script you run from the Text Editor is a one-off. An add-on turns the same code into a tool with a button in the interface, undo support, settings and a name in Preferences. This lesson shows the four building blocks: an Operator (the action), a Panel (the interface), Properties (the settings) and registration.

Blender cannot run here, so every add-on listing is read-only. To let you practice the logic, we provide a runnable stand-in: a miniature plugin registry in plain Python that follows the same register, poll, execute pattern. It teaches the structure, not the Blender API.

The shape of an add-on

A single-file add-on is a .py file with a bl_info dictionary (older versions; Blender 4.2+ extensions use a blender_manifest.toml instead, see the manual), classes that inherit Blender's types, and register and unregister functions.

Python
bl_info = {
    "name": "Scatter Cubes",
    "author": "You",
    "version": (1, 0, 0),
    "blender": (4, 0, 0),
    "location": "View3D > Sidebar > Scatter",
    "description": "Adds random cubes around the 3D cursor",
    "category": "Object",
}

import bpy
import random


class SCATTER_OT_cubes(bpy.types.Operator):
    """Scatter cubes around the 3D cursor"""
    bl_idname = "scatter.cubes"          # call it as bpy.ops.scatter.cubes()
    bl_label = "Scatter Cubes"
    bl_options = {'REGISTER', 'UNDO'}    # appears in the Adjust Last Operation panel, supports undo

    count: bpy.props.IntProperty(name="Count", default=10, min=1, max=500)
    spread: bpy.props.FloatProperty(name="Spread", default=5.0, min=0.1)

    @classmethod
    def poll(cls, context):
        return context.mode == 'OBJECT'  # only run in Object Mode

    def execute(self, context):
        origin = context.scene.cursor.location
        for _ in range(self.count):
            offset = [random.uniform(-self.spread, self.spread) for _ in range(3)]
            bpy.ops.mesh.primitive_cube_add(size=0.5, location=origin + type(origin)(offset))
        self.report({'INFO'}, f"Added {self.count} cubes")
        return {'FINISHED'}


class SCATTER_PT_panel(bpy.types.Panel):
    bl_label = "Scatter"
    bl_idname = "SCATTER_PT_panel"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'                # the N sidebar
    bl_category = "Scatter"              # the tab name

    def draw(self, context):
        layout = self.layout
        layout.operator("scatter.cubes", icon='MESH_CUBE')


classes = (SCATTER_OT_cubes, SCATTER_PT_panel)

def register():
    for cls in classes:
        bpy.utils.register_class(cls)

def unregister():
    for cls in reversed(classes):
        bpy.utils.unregister_class(cls)

if __name__ == "__main__":
    register()

Every part has a role:

  • Naming: operator class names follow CATEGORY_OT_name, panels CATEGORY_PT_name, menus CATEGORY_MT_name. bl_idname of an operator must be lowercase with one dot (scatter.cubes).
  • Properties declared as annotations (count: bpy.props.IntProperty(...), note the colon, not an equals sign) become fields in the Adjust Last Operation panel, so the user can change the count after running it.
  • poll decides whether the operator is available (greyed out otherwise).
  • execute does the work and returns {'FINISHED'} (success, creates an undo step) or {'CANCELLED'}.
  • bl_options = {'REGISTER', 'UNDO'} is what makes Ctrl+Z work.

Installing

  1. Save the file as scatter_cubes.py.
  2. In Blender: Edit > Preferences > Add-ons > Install... (or Install from Disk in newer versions), choose the file and enable its checkbox.
  3. Press N in the 3D Viewport and open the Scatter tab.

For development, run the script directly from the Text Editor: Alt+P calls register() through the __main__ block. Re-running without unregistering can raise "already registered" errors, so call unregister() first or restart Blender.

A runnable stand-in: register, poll, execute

This mock reproduces the lifecycle: a registry of operators, poll checks, execute with return codes and an undo stack. It is not Blender.

Python Stand-in: operator registry with poll, execute and undo

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Properties and settings

Besides operator properties, you can store settings on scenes or objects:

Python
class ScatterSettings(bpy.types.PropertyGroup):
    count: bpy.props.IntProperty(default=10, min=1)
    seed: bpy.props.IntProperty(default=0)

# in register():
bpy.utils.register_class(ScatterSettings)
bpy.types.Scene.scatter = bpy.props.PointerProperty(type=ScatterSettings)

# in draw():
layout.prop(context.scene.scatter, "count")
layout.prop(context.scene.scatter, "seed")

Remember to del bpy.types.Scene.scatter in unregister(). Properties on scenes are saved in the .blend file. For settings stored in Preferences, use an AddonPreferences class.

  • Add an entry to an existing menu: bpy.types.VIEW3D_MT_add.append(menu_func) where menu_func(self, context) calls self.layout.operator(...). Remove it in unregister().
  • Layout helpers: layout.row(), layout.column(), layout.box(), layout.separator(), layout.label(text=..., icon=...), layout.prop(...), layout.operator(...).
  • Never create or modify data inside draw(): it runs constantly and must only describe the interface.
  • Keyboard shortcuts: add a keymap item through bpy.context.window_manager.keyconfigs.addon.keymaps, and remove it on unregister.

Debugging add-ons

  • Open the system console to see tracebacks. Errors raised in execute also appear as a red message in the status bar.
  • Use self.report({'ERROR'}, "message") and return {'CANCELLED'} to tell the user what went wrong.
  • Reload code without restarting: Blender menu > System > Reload Scripts (F3, search "Reload Scripts").
  • Test with bpy.ops.scatter.cubes(count=5) in the Python Console.

Sharing and safety

  • Keep an Open Source license note and a version; for distribution, Blender 4.2+ supports Extensions with a manifest, hosted on extensions.blender.org.
  • Add-ons run with full user permissions. Only install add-ons from sources you trust and read what they do.
  • Avoid import of third-party packages that Blender does not ship, unless you install them into Blender's Python or bundle them (wheels in extensions).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an Operator's poll method decide?

    If poll returns False the operator is greyed out or refuses to run.
  2. 2. Which bl_options values give an operator an undo step and show it in Adjust Last Operation?

    REGISTER shows the redo panel and UNDO records an undo step.
  3. 3. Where should the code that creates objects live in a Panel?

    draw() runs constantly and must only lay out the interface. Put actions in operators.
  4. 4. How are operator properties declared in Blender 2.8 and newer?

    They are class annotations (with a colon); an equals sign gives an old-style, unsupported definition.

Summary

  • An add-on is Operators (actions), Panels (UI) and Properties (settings), registered in register() and removed in unregister().
  • Use poll, bl_options and report for usable, undoable tools.
  • Keep draw() free of side effects and clean up everything you register.
  • Only install add-ons you trust; they have full access to your machine.

Next: Rigid Body Physics