blender_vscode: debugging Blender addons from Visual Studio Code

A managed Blender session with a debugger attached

The Blender Development extension for Visual Studio Code is for Blender addon development with a Python debugger, and everything it provides is reachable from the Blender command palette menu with Ctrl+Shift+P.

The quick start is four steps. You install the extension the way you install any VS Code extension, using the id JacquesLucke.blender-development. You open the addon folder, one per workspace, and press Ctrl+Shift+P then Blender: Start. You choose a Blender executable, any Blender at or above 2.8.34, and wait for the session to launch. After that you use Blender: Reload Addons after editing your addon and Blender: Run Script to execute scripts.

The reason this is more than a launch shortcut is the debugger. The README says the terminal output appears inside VS Code and you can debug as usual with breakpoints. For anyone who has written Blender addon code, that is the whole value, because Blender's own Python environment is awkward to attach a debugger to and the usual alternative is print statements and a reload.

Two operating details are worth knowing up front. Opening Blender for the first time may take longer because dependency libraries are set up automatically, and the very first launch installs the required Python dependencies automatically, so you should keep a stable internet connection during that run.

The project is MIT licensed, the primary language is TypeScript, the default branch is master, the last push was on 2026-07-10, and the repository publishes no GitHub releases. The extension version in the manifest is 0.0.31 and the VS Code engine requirement is 1.63.0 or newer.

Symlinks are how your addon becomes visible to Blender

The mechanism that makes the whole thing work is a symlink, and the README describes it precisely.

VS Code automatically creates permanent symlinks, junctions on Windows, so your addon is visible inside Blender. There are two of them, and they are the two resource paths Blender uses. For addons it is the path given by bpy.utils.user_resource with the SCRIPTS type and the addons path, and for extensions it is the same call with the EXTENSIONS type and the vscode_development path.

That distinction matters because Blender 4.2 changed the packaging model. The README states that extensions and legacy addons, meaning addons from before Blender 4.2, are both supported, and that VS Code uses automatic logic to determine which one you are using. A migration guide is linked for moving between the two.

The symlink approach is what makes the debugging loop work. Blender imports your addon from its own resources directory, and the symlink points at your working folder, so the code Blender runs is the code you are editing, with no copy step.

The one sharp edge is documented with a warning. In some cases, uninstalling an addon using the Blender preferences user interface might lead to data loss, so the recommendation is not to use the interface to uninstall and to delete the link manually instead. The details are in EXTENSION-SUPPORT.md, which the README links twice.

The addon wizard, the reload loop, and the justMyCode setting

Scaffolding a new addon is a single command. Blender: New Addon gives you a ready-to-use addon folder, and the wizard asks which template to use, where to save it, what to name it and who is authoring it. The README advises preferring an empty folder without spaces. Once the scaffold exists you open it in VS Code and start working, and all the commands including reload and the script runners work immediately because VS Code has already created the required symlinks.

For an existing addon the rules are slightly different. The extension works with folder-based addons or extensions, and if your addon is a single file called something.py you move it into a folder and rename the file to __init__.py.

The reload loop has two settings. Blender: Reload Addons is the manual command, and it requires that Blender was started via the extension. The setting blender.addon.reloadOnSave triggers the reload automatically on save, which is the one you want once the loop is working.

Debugging is limited to workspace files by default, and the setting blender.addon.justMyCode turns that off so you can step into third-party libraries. The README attaches a caution to it, noting that this can make Blender less stable in rare cases, which is the right warning to give about stepping into a library you do not control.

The extension also exposes a Blender: New Operator command in the command list, which is the operator equivalent of the addon scaffold for a single operator rather than a whole add-on.

Environment isolation, so your daily Blender setup survives

The setting worth understanding properly is blender.environmentVariables, because it changes where Blender keeps its user files.

Set it to point Blender at a dedicated development workspace, and the value in the README is a single entry that redirects the resources directory:

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

The effect is that settings, addons and user scripts are kept separate from your daily Blender setup. That sounds like a small thing and it is not, because the extension creates permanent symlinks into Blender's resources directory, and a development addon installed into your real configuration directory is an addon that can break your everyday work.

For finer control, the README lists the individual BLENDER_USER variables, with the same shape as Blender's own documentation. There is one that replaces the default directory of all user files, and the others override when set: BLENDER_USER_CONFIG for user configuration files, BLENDER_USER_SCRIPTS for user scripts, BLENDER_USER_EXTENSIONS for user extensions, and BLENDER_USER_DATAFILES for user data files such as icons and translations.

The workspace-scoped value in the example is the important detail, since it uses the VS Code workspace folder variable so each project gets its own isolated Blender environment rather than one shared location.

The script runner, and the two ways to pass arguments

The extension also covers standalone scripts that are not full addons, which is a separate mode of working from the addon workflow.

Blender: New Script walks you through creating a script in a folder you choose. Blender: Run Script executes every script in any open Blender session that was started through VS Code, and Blender will start automatically if no instances are running, which removes the most common friction of the manual approach.

Where the script runs inside Blender is controlled by a comment or a command. Insert a comment like #context.area: VIEW_3D, or run Blender: Set Script Context, to control where scripts execute, which matters for any script that uses the current area or editor.

Arguments have two mechanisms. The setting blender.additionalArguments takes CLI arguments to a Python script, and they become available in sys.argv. The newer approach is to register the command with bpy.utils.register_cli_command, available in Blender 4.2 and newer, and use --command to call it. The README marks the newer one as the way to prefer, and the common pitfalls section says the same, advising you to prefer bpy.utils.register_cli_command when wiring command line entry points.

There is a warning attached to the whole feature, and it is a blunt one. Running scripts from VS Code occasionally crashes Blender, so keep your work saved and restart Blender if it becomes unresponsive. The related pitfall is calling sys.exit inside a Blender script, which the README links to as a gotcha in Blender's own documentation.

Where this extension is the wrong choice

The first wrong case is a workflow that only needs to run a script. If you occasionally write a Python script for Blender and run it from the text editor in Blender's own scripting workspace, you are now installing an extension, starting a managed Blender session, dealing with symlinks and a separate environment, and adding a crash mode where running the script kills the application. For occasional scripting that is a poor trade.

The second is a machine with an unreliable connection on the first launch. The extension installs the required Python dependencies automatically, and the README asks for a stable internet connection during that run. If you work on a plane or behind a restrictive network, the first launch is a problem the extension creates rather than solves.

The third is an existing setup that already works. If you have a Blender workflow that you are happy with, the symlink mechanism is invasive. It creates permanent links inside Blender's resources directory, it changes where Blender looks for user files if you set the environment variables, and it takes over how Blender is launched. The warning about data loss when uninstalling through the preferences interface is a small signal of how much the extension is inside your Blender installation.

The fourth is a team that needs a shared, reproducible setup. The configuration is a set of VS Code settings and a per-workspace environment, and the version is 0.0.31 with no GitHub releases, so there is no tagged version to pin in a shared setup and no release notes beyond the CHANGELOG file.

The alternative worth weighing is Blender's own Text Editor plus the Python console, or a standalone debugger such as a dedicated Python IDE. The extension wins on the integrated breakpoint workflow and the addon scaffold, and loses on the fact that it takes over the launch of the application you are trying to extend.

Editorial conclusion

Adopt this extension if you develop Blender addons and have been editing Python in a text editor while reloading by hand, since it gives you breakpoints in addon code, a script runner and an addon wizard in one place. Keep away if you only write occasional one-off scripts, because the machinery of starting a managed Blender session is more than you need. Before you start, read the section on uninstalling in EXTENSION-SUPPORT.md, because the README warns that uninstalling an addon through the Blender preferences interface can lead to data loss and recommends deleting the link manually instead, and note that the extension requires Blender 2.8.34 or newer and VS Code 1.63.0 or newer.

Frequently asked questions

Official sources

1. Issues
2. JacquesLucke/blender_vscode on GitHub
3. License: MIT
4. README