3D Design • • 5-8 minutes

Your first Blender extension: from manifest to sidebar panel

Diego Cortés
Diego Cortés
Full Stack Developer & SEO Specialist
Share:
Your first Blender extension: from manifest to sidebar panel
Image generated with AI

Blender 5.3 is out and the Extensions platform now takes asset libraries too. What people keep asking for, though, is the old thing: your own add-on with a panel, a shortcut and a zip that installs. Here it is, end to end.

What an Extension Is and What Blender 5.3 Changed

Since Blender 4.2 an add-on ships as an extension: a folder with a blender_manifest.toml at the root and the Python code inside. It is the same compressed package that goes to extensions.blender.org, and the difference from older add-ons is that the manifest replaces the old bl_info block as the add-on's identity card.

Add-ons with bl_info still install from disk and no removal date has been announced. The official advice is to convert them, because the manifest is what the platform reads to validate, list and update the package.

Blender 5.3, released on November 10, 2026, added a detail the launch coverage skipped: the Extensions platform is no longer only for add-ons and themes, it also accepts asset libraries. The package format is now settled, so it is worth learning it once and properly.

What does not change: your operators and panels are still Python on top of bpy, and Blender 5.x runs Python 3.13. You can confirm the exact version with sys.version from the program's Python console.

Step 1: blender_manifest.toml

The manifest is a text file at the package root. It has no logic: it declares what the extension is, which Blender version it supports and which permissions it needs. The validator reads it before the code, and if something is missing the package does not go in.

This is the manifest for a small but real add-on that renames selected objects with a prefix and numbering:

schema_version = "1.0.0"
id = "batch_rename"
version = "1.0.0"
name = "Batch Rename"
tagline = "Rename selected objects with a prefix and numbering"
maintainer = "Your Name <you@example.com>"
type = "add-on"
license = ["SPDX:GPL-3.0-or-later"]
blender_version_min = "4.2.0"
tags = ["Object"]
FieldWhat it is for
schema_versionVersion of the manifest format. Today it is 1.0.0.
idUnique lowercase identifier. It is the extension folder name and the key Blender uses to store its preferences.
versionAdd-on version. Bumping it is what triggers an update on the platform.
name and taglineVisible name and a one-line description. The tagline gets truncated, so keep it short.
maintainerWho answers for the package, with an email in angle brackets.
typeadd-on or theme.
licenseLicense in SPDX format. Publishing on the platform requires a GPL-compatible one.
blender_version_minMinimum Blender version. The useful floor is 4.2.0, when the format was born.
tagsStore categories, taken from a closed list.

Permissions, and Why the Validator Cares

If the extension opens network connections, writes outside its own folders or touches the clipboard, it has to say so in a permissions list inside the manifest. This is not bureaucracy: platform review rejects packages that do undeclared things, and the user sees the warning before installing. An add-on that downloads models without asking for network access is exactly the kind of thing that fails the filter.

Step 2: The Operator That Does the Work

The operator is the action. It has an internal identifier, a visible label and a set of options; the important one is UNDO, which records the change so Ctrl+Z reverts it like any native action.

import bpy

class OBJECT_OT_batch_rename(bpy.types.Operator):
    bl_idname = "object.batch_rename"
    bl_label = "Rename Selected"
    bl_options = {"REGISTER", "UNDO"}

    def execute(self, context):
        prefs = context.preferences.addons[__package__].preferences
        selection = sorted(context.selected_objects, key=lambda o: o.name)

        for i, obj in enumerate(selection, start=prefs.start_index):
            obj.name = "tmp_rename_%04d" % i

        for i, obj in enumerate(selection, start=prefs.start_index):
            obj.name = "%s%0*d" % (prefs.prefix, prefs.padding, i)

        return {"FINISHED"}

Two passes, not one. The first leaves every object with a temporary name that cannot collide with anything; the second applies the final name. It is the cheap way around the problem in the next section.

Why the .001 Suffix Will Bite You

Blender does not allow two objects with the same name: if you assign one that already exists, it appends .001. In batch renaming that turns into a chain of errors, because the object you rename first can take the name another one is supposed to get later. The scene ends up with Prop_01, Prop_01.001 and Prop_02 mixed together.

The fix has two parts: rename in two passes, as above, and sort the selection by something stable before numbering. context.selected_objects guarantees no order, so sorting by name keeps the result from depending on the order you clicked.

Step 3: The Sidebar Panel

The panel is interface only. It declares the space and region where it lives; here, the 3D viewport sidebar the user opens with the N key. The bl_category property is what creates the new tab.

class VIEW3D_PT_batch_rename(bpy.types.Panel):
    bl_space_type = "VIEW_3D"
    bl_region_type = "UI"
    bl_category = "Batch"
    bl_label = "Batch Rename"

    def draw(self, context):
        prefs = context.preferences.addons[__package__].preferences
        layout = self.layout
        layout.prop(prefs, "prefix")
        layout.prop(prefs, "start_index")
        layout.prop(prefs, "padding")
        layout.operator("object.batch_rename", icon="SORTALPHA")

layout.prop binds a preferences field straight to the panel with no glue code: whatever the user changes there saves itself. And if you need to show a long text that does not fit on one line, Blender 5.3 ships layout.label_multiline(), which wraps instead of cutting with an ellipsis.

Step 4: Add-on Preferences

Preferences are the right place for persistent settings. They live in a separate class, and the key detail is that bl_idname points at the package, not at an invented name: that is what lets the operator find them later.

class BatchRenamePreferences(bpy.types.AddonPreferences):
    bl_idname = __package__

    prefix: bpy.props.StringProperty(name="Prefix", default="Prop_")
    start_index: bpy.props.IntProperty(name="Start", default=1, min=0)
    padding: bpy.props.IntProperty(name="Digits", default=2, min=1, max=6)

From anywhere in the add-on they are reached with context.preferences.addons[__package__].preferences. That access path is why you should not duplicate the values in global variables: the preference is the single source of truth.

Step 5: The Keyboard Shortcut

The shortcut is registered in the add-on keymap, inside register(). There is a detail that almost everyone forgets: if you do not keep a reference to the created item, you cannot remove it when the extension is disabled, and the shortcut stays behind pointing at an operator that no longer exists.

addon_keymaps = []

def register():
    bpy.utils.register_class(OBJECT_OT_batch_rename)
    bpy.utils.register_class(VIEW3D_PT_batch_rename)
    bpy.utils.register_class(BatchRenamePreferences)

    kc = bpy.context.window_manager.keyconfigs.addon
    if kc:
        km = kc.keymaps.new(name="Object Mode", space_type="EMPTY")
        kmi = km.keymap_items.new(
            "object.batch_rename", "R", "PRESS", ctrl=True, shift=True
        )
        addon_keymaps.append((km, kmi))

def unregister():
    for km, kmi in addon_keymaps:
        km.keymap_items.remove(kmi)
    addon_keymaps.clear()
    bpy.utils.unregister_class(BatchRenamePreferences)
    bpy.utils.unregister_class(VIEW3D_PT_batch_rename)
    bpy.utils.unregister_class(OBJECT_OT_batch_rename)

Classes are registered in one order and removed in reverse. If you register them in a loop, walk the tuple with reversed() when unregistering.

Step 6: Build the Zip and Test It Like a User

The package is built from the command line, pointing at the directory that holds the manifest:

blender --command extension build --source-dir batch_rename --output-dir dist

The result is a zip with the manifest, the code and whatever you put in the folder. To test it the way another person would, open Preferences, go to the Extensions tab, open the dropdown menu and pick install from disk. During development the loop is shorter: keep the code in the user folder and use Reload Scripts on every change instead of reinstalling the zip each time.

Where User Data Goes

Never write inside the extension directory. On update that directory is replaced, and you take the user's configuration down with it. The right path is bpy.utils.extension_path_user(__package__, create=True), which returns a folder of its own per extension and per profile, outside the package.

Five Mistakes That Break an Extension

  • Wrong minimum version. Declaring 4.2 while using something that arrived in 5.3 means the extension installs and fails at run time. That is worse than not installing.
  • Relative path imports. Inside a package, import by the package module name, not by file path.
  • register() without a matching unregister(). It leaves classes, shortcuts and handlers alive after disabling.
  • Writing into the extension folder. It is gone on the first update.
  • Undeclared permissions. Review finds it and the package is not published.

Publishing on extensions.blender.org

Publishing is the last step and the dullest: create an account, upload the zip, wait for a moderator's review. Review checks that the manifest is coherent, that the license is GPL-compatible and that the add-on does what its tagline says. Updates are not uploaded as a new package: you upload the same id with a higher version, and users who have it installed get the notice.

If you would rather skip review, the zip can also be distributed on your own and installed from disk. That is what most in-house studio add-ons do: same format, no store.

Conclusion

When you are done you have the four pieces every real extension has: an operator that does the work, a panel that exposes it, preferences that persist and a shortcut that cleans itself up. The rest is widening the example: swap the renaming for the operation you actually need and rebuild the zip. If you want the context of the release that opened the platform to asset libraries, see the breakdown of what Blender 5.3 changed. And if you would rather start smaller, the blog keeps publishing Blender Python tricks that need no manifest at all.

Categories