DocumentationSubstance 3D

Debugging plugins using Visual Studio Code

Last update: Thu Feb 26 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

As a workflow standard for many developers, the Visual Studio Code IDE is available to debug Python plugins.

WARNING
The debugpy.listen() method may let anyone who can connect to the specified port execute arbitrary code within the debugged process.
Therefore, debugging should only be set up and performed on secure networks.

In order to set up the synergy between Visual Studio Code and Substance 3D Designer, please follow these steps:

  1. Install Visual Studio Code and the Python extension.

  2. Install the debugpy Python module.

    note note
    NOTE
    Make sure that the Python interpreter in Designer can find the ‘debugpy’ module. The easiest way to do it is to add the directory where the ‘debug’ module is to the PYTHONPATH environment variable. An alternative could be to modify sys.path in your script to add the path to the debugpy module.

    1. Launch the application, open the Python Editor and **run the following code**:

    code language-none 
    
import sys



debugpy_path = '/path/to/debugpy/module'

debugpy_port = 5678

designer_py_interpreter = '/path/to/python/executable/bundled/in/designer'



if not debugpy_path in sys.path:

    sys.path.append(debugpy_path)



import debugpy



debugpy.configure(python=designer_py_interpreter)

debugpy.listen(debugpy_port)

  3. In Visual Studio Code, open your project and create a launch.json file. Add the following into the file:

    code language-none 
    
{

    "name": "Attach to Designer",

    "type": "python",

    "request": "attach",

    "port": <port number used in the script above>,

    "host": "127.0.0.1"

}

  4. Click on the Debug icon, create or edit your debugger configuration, if needed.

  5. Select the Python: Attach to Designer configuration and click on Start Debugging.

    You should now be able to set breakpoints, step trough the code, and use all the other features of Visual Studio Code’s debugger.

recommendation-more-help
dd48abc6-e399-43d2-9777-578ec70c5a23