How to Create Extensions

Creating an extension takes only a few steps:

  1. Open the directory containing the add-on code or theme file.

  2. Add a blender_manifest.toml file with all the required meta-data (name, maintainer, ...).

  3. Use the Blender command-line tool to build the extension .zip file.

How to publish to the Blender Extensions Platform:

The extension will be held for review, and published once the moderation team approves it.

Extension files

An extension is shared as a .zip archive containing a manifest file and other files. The expected files depend on the extension type.

Add-on extension

Add-ons need at least the manifest and an __init__.py file, while more complex add-ons have a few different .py files or wheels together.

  1. my_extension-0.0.1.zip
  2. ├─ __init__.py
  3. ├─ blender_manifest.toml
  4. └─ (...)

Theme extension

A theme extension only needs the manifest and the .xml theme file.

  1. my_extension-0.0.1.zip
  2. ├─ blender_manifest.toml
  3. └─ theme.xml

Note

Extensions can optionally have all its files inside a folder (inside the archive). This is a common behavior when saving a repository as ZIP from version-control platforms.

Manifest

A manifest is a file with all the meta-data required for an extension to be processed. This example is a good starting point to the blender_manifest.toml that should be inside the .zip.

  1. schema_version = "1.0.0"
  3. # Example of manifest file for a Blender extension
  4. # Change the values according to your extension
  5. id = "my_example_extension"
  6. version = "1.0.0"
  7. name = "Test Extension"
  8. tagline = "This is another extension"
  9. maintainer = "Developer name <[email protected]>"
  10. # Supported types: "add-on", "theme"
  11. type = "add-on"
  13. # Optional link to documentation, support, source files, etc
  14. # website = "https://extensions.blender.org/add-ons/my-example-package/"
  16. # Optional list defined by Blender and server, see:
  17. # https://docs.blender.org/manual/en/dev/advanced/extensions/tags.html
  18. tags = ["Animation", "Sequencer"]
  20. blender_version_min = "4.2.0"
  21. # # Optional: Blender version that the extension does not support, earlier versions are supported.
  22. # # This can be omitted and defined later on the extensions platform if an issue is found.
  23. # blender_version_max = "5.1.0"
  25. # License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
  26. # https://docs.blender.org/manual/en/dev/advanced/extensions/licenses.html
  27. license = [
  28.   "SPDX:GPL-2.0-or-later",
  29. ]
  30. # Optional: required by some licenses.
  31. # copyright = [
  32. #   "2002-2024 Developer Name",
  33. #   "1998 Company Name",
  34. # ]
  36. # Optional list of supported platforms. If omitted, the extension will be available in all operating systems.
  37. # platforms = ["windows-x64", "macos-arm64", "linux-x64"]
  38. # Other supported platforms: "windows-arm64", "macos-x64"
  40. # Optional: bundle 3rd party Python modules.
  41. # https://docs.blender.org/manual/en/dev/advanced/extensions/python_wheels.html
  42. # wheels = [
  43. #   "./wheels/hexdump-3.3-py3-none-any.whl",
  44. #   "./wheels/jsmin-3.0.1-py3-none-any.whl",
  45. # ]
  47. # # Optional: add-ons can list which resources they will require:
  48. # # * files (for access of any filesystem operations)
  49. # # * network (for internet access)
  50. # # * clipboard (to read and/or write the system clipboard)
  51. # # * camera (to capture photos and videos)
  52. # # * microphone (to capture audio)
  53. # #
  54. # # If using network, remember to also check `bpy.app.online_access`
  55. # # https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
  56. # #
  57. # # For each permission it is important to also specify the reason why it is required.
  58. # # Keep this a single short sentence without a period (.) at the end.
  59. # # For longer explanations use the documentation or detail page.
  60. #
  61. # [permissions]
  62. # network = "Need to sync motion-capture data to server"
  63. # files = "Import/export FBX from/to disk"
  64. # clipboard = "Copy and paste bone transforms"
  66. # Optional: build settings.
  67. # https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
  68. # [build]
  69. # paths_exclude_pattern = [
  70. #   "__pycache__/",
  71. #   "/.git/",
  72. #   "/*.zip",
  73. # ]

Required values:

blender_version_min:

Minimum supported Blender version - use at least 4.2.0.

id:

Unique identifier for the extension.

license:

List of licenses, use SPDX license identifier.

maintainer:

Maintainer of the extension.

name:

Complete name of the extension.

schema_version:

Internal version of the file format - use 1.0.0.

tagline:

One-line short description - cannot end with punctuation.

type:

“add-on”, “theme”.

version:

Version of the extension - must follow semantic versioning.

Optional values:

blender_version_max:

Blender version that the extension does not support, earlier versions are supported.

website:

Website for the extension.

copyright:

Some licenses require a copyright, copyrights must be “Year Name” or “Year-Year Name”.

tags:

List of tags. See the list of available tags.

platforms:

List of supported platforms. If omitted, the extension will be available in all operating systems. The available options are [“windows-x64”, “windows-arm64”, “macos-x64”, “macos-arm64”, “linux-x64”]

wheels:

List of relative file-paths Python Wheels.

permissions:

Add-ons can list which resources they require. The available options are files, network, clipboard, camera, microphone. Each permission should be followed by an explanation (short single-sentence with no end punctuation (.)).

Optional values for “build”:

These values are only used by the build sub-command.

paths:

A list of file-paths relative to the manifest to include when building the package.

paths_exclude_pattern:

A list of file-path patterns to exclude include when building the package.

The pattern matching is compatible with gitignore.

Note that setting this value isn’t supported when paths is also declared.

If the [build] table isn’t declared the following default is used:

  1. [build]
  2. paths_exclude_pattern = [
  3.   "__pycache__/",
  4.   ".*",
  5.   "*.zip",
  6. ]

Reserved:

These values must not be declared in a TOML and are reserved for internal use.

  • [build.generated]

Note

All the values present in the manifest file must be filled (i.e., cannot be empty, nor text "", nor list []).

If you don’t want to set one of the optional values just exclude it from the manifest altogether.

Command-line

Extensions can be built, validated & installed via command-line.

To build the package defined in the current directory use the following commands:

  1. blender --command extension build

See build docs.

—

To validate the manifest without building the package:

  1. blender --command extension validate

You may also validate a package without having to extract it first.

  1. blender --command extension validate add-on-package.zip

See validate docs.

See also

Extensions Command Line Arguments.

Third party extension sites

If you want to host the extensions yourself, see the Creating an Extensions Repository docs.