Blender Addon Template

Minimal template for building Blender extensions with Python wheel dependencies, cross-platform builds, and GitHub Actions CI/CD.

---

Create a new addon (recommended)

Generate a fully configured project interactively — no need to clone this repo:

bash <(curl -s https://raw.githubusercontent.com/josemarinfarina/blender_addon_template/main/create_addon.sh)

The script asks for addon name, author, description, Blender version, etc. and writes all files with your data already in place.

Or locally, if you have the repo: ./create_addon.sh

---

Repository structure

.
├── create_addon.sh              # Interactive scaffolding script (like create-next-app)
├── blender_manifest.toml        # Blender extension manifest (metadata + wheels)
├── build_extension.sh           # Assembles build_temp/ and runs blender extension build
├── my_addon/                    # Addon source code (rename to your addon name)
│   └── __init__.py
├── constraints/                 # Pinned dependency lists per platform
│   ├── base.txt                 #   flexible ranges (documentation / pip install)
│   ├── linux-x64.txt            #   pinned versions for reproducible wheel downloads
│   ├── windows-x64.txt
│   ├── macos-x64.txt
│   └── macos-arm64.txt
├── scripts/
│   └── fetch_wheels.sh          # Downloads wheels for all 4 platforms into wheels/
├── wheels/                      # Created by fetch_wheels.sh (gitignored .whl files)
├── dist/                        # Build output (gitignored)
├── build_temp/                  # Temporary build dir (gitignored)
├── .github/
│   └── workflows/
│       └── build-extension.yml  # CI: fetch wheels → download Blender → build → upload artifacts
├── .gitignore
├── LICENSE
└── README.md

Manual setup (alternative)

If you prefer to clone this repo instead of using create_addon.sh:

1. Rename the addon

Replace my_addon everywhere:

• Rename the my_addon/ directory.
• Update ADDON_DIR default in build_extension.sh.
• Update paths in .github/workflows/build-extension.yml.
• Update id, name, and other fields in blender_manifest.toml.
• Update bl_info in __init__.py.

2. Add dependencies

If your addon needs third-party Python packages:

1. Add the package with flexible version ranges to constraints/base.txt.
2. Pin exact versions in each platform file (constraints/linux-x64.txt, etc.).
3. Run scripts/fetch_wheels.sh to download all wheels into wheels/.
4. List the downloaded .whl filenames in the wheels array of blender_manifest.toml.

Tip: Blender already ships numpy. Do not include it in your constraints.

3. Build locally

# 1. Download wheels (only needed once, or when deps change)
chmod +x scripts/fetch_wheels.sh
./scripts/fetch_wheels.sh

# 2. Build the extension (requires `blender` on PATH or BLENDER_BIN set)
chmod +x build_extension.sh
./build_extension.sh

Per-platform .zip files are written to dist/.

4. CI/CD (GitHub Actions)

The included workflow (.github/workflows/build-extension.yml) runs on every push to main/master or on tags matching v*. It:

1. Checks out the repo.
2. Fetches wheels for all platforms via scripts/fetch_wheels.sh.
3. Downloads a Blender release.
4. Builds the extension with --split-platforms.
5. Uploads per-platform .zip artifacts.

Update the BLENDER_VERSION variable in the workflow to match your target.

---

Key concepts

constraints/

Each platform file lists pinned dependency versions. fetch_wheels.sh reads these and uses pip download --only-binary=:all: --platform=<tag> to fetch the correct wheels without installing anything locally.

blender_manifest.toml

The extension manifest tells Blender about your addon. The wheels array lists every .whl that must be shipped — both universal (py3-none-any) and platform-specific (cp311-cp311-<platform>).

build_extension.sh

Copies only the necessary files (manifest, addon source, wheels) into a temporary build_temp/ directory, then invokes blender --command extension build --split-platforms. This keeps the repository clean — test files, scripts, docs, etc. are never included in the built extension.

wheels/ directory

Downloaded .whl files live here but are gitignored. They are fetched fresh at build time (locally or in CI). Only the wheels/ directory itself is committed (empty).

---

License

This template is released under the GPL-3.0-or-later license.