How to Convert Your Blender Add-on to an Extension (and Why You Should)

Why Convert Your Blender Add-on?

Blender 4.2 marked a turning point for developers: the familiar add-on system evolved into a more structured, platform-integrated Extensions framework.

While legacy add-ons still function, the new system offers a cleaner, more scalable way to distribute tools, complete with dependency bundling, metadata standardization, and direct integration with Blender’s Extension Platform.

If you’ve built an add-on, converting it to an extension isn’t just about staying current, it’s about future-proofing your work and making it easier for users to install, update, and trust your tools. This guide walks you through the conversion process step-by-step, highlighting key changes, common pitfalls, and practical tips to help you make the switch smoothly.

Whether you’re maintaining a lightweight utility or a full-featured toolkit, the transition is simpler than it looks, and absolutely worth the effort.

Why I Wrote This Guide

As someone who reviews Blender products daily, I’ve had a front-row seat to the evolving submission landscape. With the introduction of the extension system, I genuinely expected creators to pivot quickly and embrace the cleaner packaging, standardized structure, and improved user experience that extensions offer. Yet, the majority of submissions still arrive as traditional add-ons.

It’s a trend that surprises me, and it’s precisely why I felt compelled to write this article: to shed light on the shift, highlight the benefits of extensions, and encourage more developers to make the leap.

Key Takeaways: 

  • Blender 4.2 introduces the Extensions system, replacing traditional add-ons for cleaner distribution.
  • Extensions use a blender_manifest.toml file instead of bl_info.
  • You can now bundle Python dependencies directly with your extension.
  • Extensions require declared permissions for better transparency and security.
  • Converting is mostly about reorganizing files and updating metadata — your core code still works.

Understanding the Shift: Add-ons vs Extensions

Blender’s new Extensions system isn’t a complete reinvention; it’s a refinement. If you’ve built add-ons before, most of your core logic still applies. But the way you package, distribute, and declare your tool’s metadata has changed. Here’s what’s new, what’s familiar, and what’s fading out.

Add-on vs Extension at a Glance

What Extensions Offer That Add-ons Don’t

Extensions introduce several improvements:

  • Manifest File (blender_manifest.toml): Replaces the old bl_info dictionary with a standardized metadata file.
  • Dependency Bundling: You can include Python Wheels directly in your extension, making it easier to manage third-party libraries.
  • Platform Distribution: Extensions are designed to be distributed via Blender’s official Extension Platform, with versioning, updates, and permissions built in.
  • Permission Declaration: Extensions must explicitly declare what they access (e.g. internet, file system), improving transparency and security.
  • Cleaner Packaging: The folder structure is standardized, making it easier to test, share, and maintain.

What Stays the Same

Despite the new system, many fundamentals remain:

  • Python-Based Logic: Your scripts still use Python and Blender’s API.
  • UI Panels and Operators: You still register panels, operators, and properties the same way.
  • Registration Functions: register() and unregister() are still required.
  • Modular Design: You can still split your code across multiple modules and use relative imports.

What’s Deprecated or Discouraged

Some practices from the add-on era don’t translate well to extensions:

  • ❌ Using bl_info: This is replaced by blender_manifest.toml.
  • ❌ Hardcoded Paths or Writable Directories: Extensions must not assume write access to their own folder.
  • ❌ Loose Packaging: Files must be bundled inside a folder named after the extension’s id.
  • ❌ Unbundled Dependencies: External libraries should be included as Wheels or avoided entirely.

Step-by-Step Blender Extension Conversion Guide

1. Restructure Your Add-on

Your add-on must be self-contained, no external dependencies unless bundled. Avoid writing to your own directory; use Blender’s provided utility for user directories.

2. Create a Manifest File

Replace the old bl_info dictionary with a manifest.toml file. This file defines metadata and permissions.

Example manifest.toml:

id = "your_addon_id" 
tagline = "Short description of your extension" 
version = "1.0.0" 
license = "SPDX:GPL-2.0-or-later" 
maintainer = "Your Name"

Include any required permissions and supported platforms. Be concise, longer explanations go in your documentation.

3. Update Your Code

  • Replace references to your module name with __package__.
  • Use relative imports throughout your code.
  • If you rely on external Python modules, bundle them using Python Wheels.

4. Test Thoroughly

Install your extension via Blender’s Extensions menu.

Test it in both the Extensions and Add-ons panels, some setups behave differently, so it’s worth double-checking.

Check for errors in the Console window and ensure all dependencies are properly bundled.

Tips and Gotchas

Your package folder name should match the id in your manifest.toml.

Avoid assuming your directory is writable, this breaks in system repositories.

If your add-on depends on another, bundle them together and check for duplicate registrations.

Structure your ZIP file like this:

your_addon_id 
            ├── __init__.py
            ├── other_module.py
            └── manifest.toml

Make sure the ZIP contains the folder named after your id, not just loose files.

Final Thoughts

Converting your add-on to an extension isn’t just about ticking boxes; it’s about aligning with Blender’s future and giving your users a smoother experience. Once you’ve made the switch, you’ll find your tools easier to maintain, distribute, and evolve. The Blender community is moving forward, and now your add-on can too.

Thanks for reading!

Adrian