[!TIP] Check CHANGELOG for changes and new features.

Prefer the previous layout? Browse the classic README.

Blender VS Code

Blender addon development with python debugger. Everything you need is available through the Blender command palette menu (press Ctrl+Shift+P).

Table of Contents

• Blender VS Code
  • Table of Contents
  • Quick Start
  • Addon Development
    • Creating a new addon
    • Opening an existing addon
    • Environment Isolation
  • Script Tools
  • Customization & Shortcuts
    • Keyboard Shortcuts
  • Troubleshooting & Logs
  • Status & Contribution

Quick Start

1. Install the extension the same way you install any VS Code extension (id: JacquesLucke.blender-development).
2. Open the addon folder (one per workspace) and press Ctrl+Shift+P → Blender: Start.
3. Choose a Blender executable (any Blender ≥ 2.8.34) and wait for the session to launch.
4. Use Blender: Reload Addons after editing your addon and Blender: Run Script to execute scripts.

Opening Blender for the first time may take longer because dependency libraries are set up automatically.

Addon Development

Extensions and legacy addons (pre Blender 4.2) are supported. For migration guide visit Legacy vs Extension Add-ons. VS code uses the automatic logic to determine if you are using addon or extension

[!NOTE] VS Code automatically creates permanent symlinks (junctions on Windows) so your addon is visble inside Blender:

• Addons: bpy.utils.user_resource("SCRIPTS", path="addons")
• Extensions: bpy.utils.user_resource("EXTENSIONS", path="vscode_development")

Creating a new addon

• Run Blender: New Addon to scaffold a ready-to-use addon folder. The wizard asks which template to use, where to save the addon (prefer an empty folder without spaces), what to name it, and who is authoring it.
• Once the scaffold exists, open it in VS Code to start developing. All commands, including reload and script runners, work immediately because VS Code creates the required symlinks.

Opening an existing addon

• This extension works with folder-based addons or extensions. If your addon is just single file something.py, move it into a folder and rename the file to __init__.py.
• Open the folder for your addon in VS Code, run Ctrl+Shift+P → Blender: Start, and point the command at a Blender executable (Blender ≥ 2.8.34). The terminal output appears inside VS Code and you can debug as usual with breakpoints.
• The very first launch can take longer because Blender installs the required Python dependencies automatically; keep a stable internet connection during that run.
• Debugging is limited to workspace files by default. Disable blender.addon.justMyCode if you want to step into third-party libraries (caution: this can make Blender less stable in rare cases).
• Use Blender: Reload Addons after each change (requires Blender started via the extension).
• Enable blender.addon.reloadOnSave to trigger reload automatically on save.

[!WARNING] In some cases uninstalling addon using Blender Preferences UI interface might lead to data loss. So don't use UI to uninstall, just delete the link manually.

Environment Isolation

Set blender.environmentVariables to point Blender to a dedicated development workspace:

"blender.environmentVariables": {
  "BLENDER_USER_RESOURCES": "${workspaceFolder}/blender_vscode_development"
}

Environment Variables:
  $BLENDER_USER_RESOURCES  Replace default directory of all user files.
                           Other 'BLENDER_USER_*' variables override when set.
  $BLENDER_USER_CONFIG     Directory for user configuration files.
  $BLENDER_USER_SCRIPTS    Directory for user scripts.
  $BLENDER_USER_EXTENSIONS Directory for user extensions.
  $BLENDER_USER_DATAFILES  Directory for user data files (icons, translations, ..).

Script Tools

This extension helps you write, run, and debug standalone Blender scripts that are not full addons.

[!WARNING] Running scripts from VS Code occasionally crashes Blender. Keep your work saved and restart Blender if it becomes unresponsive. Don't go crazy with you scripts!

• Execute Blender: New Script and follow the prompts to create a script in your chosen folder.
• Run Blender: Run Script to execute every script in any open Blender session started through VS Code. Blender will automatically start if no instances are running.
• Insert a comment like #context.area: VIEW_3D or run Blender: Set Script Context to control where scripts execute.
• Pass CLI arguments by adding them after -- in blender.additionalArguments (they become available in sys.argv).

Common pitfalls:

• Avoid calling sys.exit inside Blender scripts (see sys.exit gotcha).
• Prefer bpy.utils.register_cli_command when wiring command line entry points.

Customization & Shortcuts

The extension is driven by settings (search for blender. inside VS Code settings). A few useful ones:

• blender.additionalArguments: pass extra CLI flags and optionally a default .blend file (prefer this as the last argument).
• blender.preFileArguments / blender.postFileArguments: control where Blender expects file names in the argument list.
• blender.executables: register frequently used Blender installations and mark one with "isDefault": true to keep prompts silent.
• blender.addon.justMyCode: disable to step into third-party libraries while debugging.
• blender.addon.reloadOnSave: reload addons every time a workspace file changes while Blender is running.
• blender.addon.logLevel: control the verbosity of the Blender output channel for debugging.

Keyboard Shortcuts

Add entries to keybindings.json to trigger commands:

{
  "key": "ctrl+h",
  "command": "blender.start"
}

For advanced usage (choose a specific executable or script):

{
  "key": "ctrl+h",
  "command": "blender.start",
  "args": {
    "blenderExecutable": { "path": "C:\\path\\blender.exe" },
    "script": "C:\\path\\script.py"
  }
}

Run scripts with shortcuts as well:

{
  "key": "ctrl+shift+enter",
  "command": "blender.runScript",
  "when": "editorLangId == 'python'"
}

Troubleshooting & Logs

• Use the latest VS Code and Blender builds.
• Check CHANGELOG.md for breaking changes.
• Search issues on GitHub before filing a new one.
• Enable debug logs via blender.addon.logLevel and inspect the Blender output channel in VS Code.

Status & Contribution

• The extension is no longer in active feature development.
• Bugs are welcome; please file issues with as much detail as possible.
• Want to help? Follow the instructions in DEVELOPMENT.md to get started.