Run and debug in Blender

Blender Development provides three Blender run configurations:

• Launch Blender starts the interactive Python runtime for normal Run and Debug workflows.
• Run Command executes a standalone Blender command without starting the plugin’s Python runtime.
• Build or Validate Extension packages or validates a Blender Extension with dedicated path controls.

Prerequisites

• PyCharm 2026.1 or newer
• Blender 4.2 or newer
• A project configured in Project Blender Manager

Configure a launch

1. Open Project Blender Manager.
2. Select a detected Blender installation, or enable Use a custom installation path and choose the executable or macOS application bundle.
3. Under Run and Debug, confirm the project source folder and add-on symlink name.
4. Set optional Blender arguments, log level, environment variables, and extra script directories.
5. Open Run > Edit Configurations and add Blender > Launch Blender.

Project Blender Manager saves changes as you edit. Project environment variables override application variables with the same name. Additional Blender arguments are appended to the generated launch command.

Run or debug

• Run starts Blender and attempts to refresh and enable the configured add-on or extension. It does not attach hot reload or advanced debugging features.
• Debug starts the bundled runtime, loads configured add-on roots, starts debugpy, and asks PyCharm to attach automatically.

Enable Reload on Save in Project Blender Manager to reload the configured add-on after saving files during Debug.

Caution

Debugger attach requires PyCharm 2026.1 or newer and the debugpy debugger mode. Runtime commands use a separate channel and may remain available even when debugger attachment fails.

Run a Blender command

Use Run Command for operations that use Blender’s --command interface:

1. Open Run > Edit Configurations.
2. Add Blender > Run Command.
3. Select a command and enter its arguments. Do not enter --command or -c; the configuration adds it automatically.
4. Run the configuration.

For example, extension list runs the equivalent of:

blender --command extension list

Command mode implies background execution. Project launch arguments for the interactive runtime are not added, although the configured Blender log level is still applied.

Build or validate an extension

1. Open Run > Edit Configurations.
2. Add Blender > Build or Validate Extension.
3. Select Build or Validate.
4. Select the extension source directory or validation archive under Source path.
5. For Build, select the package destination under Output directory.
6. Run the configuration.

Build runs the equivalent of:

blender --command extension build --source-dir SOURCE --output-dir OUTPUT

Validate runs blender --command extension validate SOURCE. Relative paths resolve from the project root. Each run configuration can override the defaults from Project Blender Manager.

Runtime commands

While a Debug runtime session is active, use these commands from the Tools menu or plugin tool window:

• Run Script in Blender sends the selected Python file to Blender and is also available from the editor context menu.
• Reload Add-on in Blender reloads the configured add-on or extension.
• Stop Blender Runtime ends the active Blender process.

The generated bootstrap script and runtime session state are removed when Blender exits. Stale scripts are cleaned on a later IDE startup.