Getting Started

Installation

Install PyCharm 2026.1 or newer, then install Blender Development for PyCharm:

1. Download the latest Blender Development for PyCharm plugin archive from the product page.
2. Open PyCharm and go to Settings (or Preferences on macOS) → Plugins.
3. Select the gear icon, choose Install Plugin from Disk, and select the downloaded archive.
4. Confirm the installation and restart PyCharm if prompted. The plugin is installed when it appears in the Installed tab.

Starting a new project

To Create a Blender Extension project, ensure that you’ve followed [Installation] first, then proceed with the following steps:

1. Open PyCharm and create a new project.
2. Choose the Blender Project project type in the left sidebar.
3. Choose whether you want an Add-on or Extension
   • Extension generates the blender-manifest required for the extension platform post Blender 4.2
4. Configure the project’s Python environment and Blender SDK. The Plugin will recommend the appropriate Interpreter version based on your selected Blender SDK.
   • For Advanced options such as addon_id, min/max blender version, tags, website, and permissions, scroll all the way down to the bottom of the Wizard and expand Advanced Settings
5. Once configured, create the project and begin development

Project Structure

The files created by the wizard depend on whether you select Add-on or Extension and which optional files you enable. The source folder contains the Blender code and is configured as a source root in PyCharm.

• Add-on: The wizard creates a single Python add-on file in the source folder. It does not need a blender_manifest.toml.
• Extension: The wizard creates extension source code and a blender_manifest.toml containing the extension metadata required by Blender’s extension platform.

For example, a fresh Extension project created as Blender_Extension has this structure (the contents of .idea/ and .venv/ are collapsed):

Blender_Extension/
├── .idea/                  # PyCharm project settings
├── .venv/                  # Local Python environment
├── src/
│   ├── __init__.py         # Extension Python module
│   └── blender_manifest.toml
├── LICENSE
└── pyproject.toml

The wizard can also generate project files such as pyproject.toml, a README, a GPL license, and optional example code. A .venv/ directory appears only when you choose a local virtual environment; other interpreter choices use their own locations. Your project may therefore contain different files from another project created with the wizard.

Managing and running the project

The Project Blender Manager tool window keeps the project’s Blender settings in one place. You can choose a detected Blender installation or a custom path; set the add-on name, extension source folder, launch arguments, log level, and optional startup .blend file; and control reload on save and debugger scope. It also provides add-on reload and workspace saving actions, plus script directories and environment variables for Blender runs.

The plugin includes Launch Blender, Run Command, and Build or Validate Extension run configurations. Launch Blender supports a development loop: debug the extension in Blender and use Reload on Save to load source changes without repeatedly building a ZIP, installing it, restarting Blender, and uninstalling it. Run Command handles Blender commands, while Build or Validate Extension checks and packages the extension when needed.

Developing a Blender extension

1. Edit src/__init__.py to implement your add-on. Keep its register() and unregister() functions working so Blender can enable and disable it. Follow Blender’s add-on development guidance for extension packages and imports.
2. Update src/blender_manifest.toml with your extension’s ID, version, name, supported Blender version, license, and any permissions it needs. See Blender’s manifest reference and creation guide.
3. Develop and debug with the plugin’s Blender launch configuration. With Reload on Save enabled in Project Blender Manager, save your source changes to reload the add-on during the running session.
4. When you are ready to check or package the extension, use the Build or Validate Extension run configuration. Choose Validation in the Operation menu to check the extension, or Build to create an installable ZIP. For a build, select an Output directory for the ZIP. Make sure a Blender executable is selected in Project Blender Manager before running the configuration.
5. Install the generated ZIP from disk in Blender and test the packaged extension before sharing it. Blender’s extension command-line reference covers additional build and validation options.

Before publishing to the official Extensions Platform, review Blender’s add-on submission guidelines and test the ZIP in a clean Blender installation.