{"id":13683255,"url":"https://github.com/AlansCodeLog/blender-debugger-for-vscode","last_synced_at":"2025-04-30T12:34:11.640Z","repository":{"id":28565309,"uuid":"118268455","full_name":"AlansCodeLog/blender-debugger-for-vscode","owner":"AlansCodeLog","description":"Blender addon for remote debugging Blender with VS Code (and Visual Studio)","archived":false,"fork":false,"pushed_at":"2022-12-20T22:35:35.000Z","size":310,"stargazers_count":299,"open_issues_count":3,"forks_count":36,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-08-02T13:35:11.089Z","etag":null,"topics":["blender","blender-addon","blender-debugger","blender-scripts","debug","debugging","vscode"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlansCodeLog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-20T18:13:30.000Z","updated_at":"2024-07-31T09:23:14.000Z","dependencies_parsed_at":"2023-01-14T09:03:55.645Z","dependency_job_id":null,"html_url":"https://github.com/AlansCodeLog/blender-debugger-for-vscode","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlansCodeLog%2Fblender-debugger-for-vscode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlansCodeLog%2Fblender-debugger-for-vscode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlansCodeLog%2Fblender-debugger-for-vscode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlansCodeLog%2Fblender-debugger-for-vscode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlansCodeLog","download_url":"https://codeload.github.com/AlansCodeLog/blender-debugger-for-vscode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224212094,"owners_count":17274358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blender","blender-addon","blender-debugger","blender-scripts","debug","debugging","vscode"],"created_at":"2024-08-02T13:02:05.468Z","updated_at":"2024-11-12T03:30:44.215Z","avatar_url":"https://github.com/AlansCodeLog.png","language":"Python","funding_links":[],"categories":["Python","👩🏽‍💻Development [^](#table)","Modeling, Sculpting \u0026 Texturing"],"sub_categories":["Scripting/Developing [^](#table)","Blender: Plugins \u0026 Addons"],"readme":"# Blender Debugger for VS Code (and Visual Studio)\n\nInspired by [Blender-VScode-Debugger](https://github.com/Barbarbarbarian/Blender-VScode-Debugger) which was itself inspired by this [remote_debugger](https://github.com/sybrenstuvel/random-blender-addons/blob/master/remote_debugger.py) for pycharm as explained in this [Blender Developer's Blog post](https://code.blender.org/2015/10/debugging-python-code-with-pycharm/).\n\nSince the VS Code one wasn't really well documented and it looked kind of dead, once I figured it out, I was just going to add the documentation, but then I ended up rewriting the whole thing.\n\nNow it can:\n\n- Auto-detect where python is and auto set the path to debugpy if installed.\n- Tell you when the debugger has actually attached.\n\n![Image Showing VS Code side by side with Blender paused at a breakpoint. In the console, a \"Debugger is Attached\" Statement is printed.](./Example.png)\n\n# How to Use\n\nI have made a video (click the image below) for those who just started messing with python in Blender or programming in general, but if you're semi-familiar with Python, VS Code, and the command line the following should make sense. If you have any questions or suggestions, don't hesitate to file an issue.\n\n#### NOTES/EDITS\n- This video was done with blender 2.79, but everything still works mostly the same. Only changes are:\n\t- Blender changed the default shortcut to the search menu.\n\t- **ptvsd has been replaced by debugpy**\n\t- Blender now requires you enable `Settings =\u003e Interface =\u003e Developer Extras` before you can see the commands.\n\n\u003cp align=\"center\" style=\"position:relative;\"\u003e\n\t\u003ca href=\"https://www.youtube.com/watch?v=UVDf2VSmRvk\" title=\"Click to go to Video\"\u003e\n\t\t\u003cimg alt=\"youtube video\" src=\"https://img.youtube.com/vi/UVDf2VSmRvk/maxresdefault.jpg\" height=\"300\" style=\"margin:0 auto;\" /\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\n## Note on Downloading\n\n**You must down it with the the green `Clone or Download` button above. DO NOT download it from releases!**\n\nThis is because blender has a problem with the periods in the name from the version number. It used to be you could rename the zip, but this no longer works, you'll get an error when you try to enable the addon. The onyl fix is to go where the addon was installed and rename the folder there.\n\n## Installing Python and Getting Debugpy\n\nInstall Python 3 with pip and check add to PATH.\u003csup id=\"n1\"\u003e[1](#f1)\u003c/sup\u003e\n\n- If you already have python installed and you can run it from the command line (aka PATH is set), the addon should find it. It checks `where python` or `whereis python` or `which python` to try and determine where python is and uses the first path given\u003csup id=\"n2\"\u003e[2](#f2)\u003c/sup\u003e.\n- If you are using something like Conda and want to use a virtual environment, to have the addon auto-detect the path you can: activate the environment, run Blender from the command line, and it should work.\n\n`pip install debugpy`\n\n- For Visual Studio, the debugpy version that works depends on the Visual Studio version. I have never used Visual Studio, but you can find more info on setting everything up here: [Remotely Debugging Python Code on Linux](https://docs.microsoft.com/en-us/visualstudio/python/debugging-python-code-on-remote-linux-machines#connection-troubleshooting). (it is not Linux specific)\n\n## Setting up your Addon\n\nThis is the most important part. Otherwise it won't work. I thought it was my VS Code config but no, it was this.\n\nIn Blender go to: `User Preferences \u003e File` and set the path to `Scripts` to the folder you're developing your addon in (e.g: \"C:\\Code\\Blender Stuff\") BUT the folder must look like this:\n\n```\nBlender Stuff\n└── addons\n\t├── your-addon-folder\n\t\t├── __init__.py\n\t\t├── ...etc\n\t├── another-addon\n\t├── ...\n```\n\nSee [Blender Docs =\u003e Installing Add-ons =\u003e User-Defined Add-on Path](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#:~:text=Add%20a%20subdirectory%20under%20my_scripts%20called%20addons%20(it%20must%20have%20this%20name%20for%20Blender%20to%20recognize%20it) for details.\n\nNow remove your addon from Blender if you had installed it manually already, save settings, and when you restart your addon should be installed automatically.\n\n## Setting up this Addon\n\nInstall the addon.\n\nIf it did not find the path it'll say \"debugpy not found\", you'll have to set it manually. It's wherever python is + \"\\lib\\site-packages\". NO trailing backslash.\n\nIf you want, increase the timeout for the confirmation. It'll print \"Waiting...\" in the console every second until it prints it's timedout. This does not mean the server has timedout *just* the confirmation listener.\n\nIf you're using Blender 2.9+ you must turn on `Developer Extras` (`Preferences =\u003e Display =\u003e Developer Extras`) if you haven't already, otherwise the addon's commands won't turn up in the search.\n\nOpen up Blender's search (default shortcut: F3), type \"Debug\".\n\nClick `Debug: Start Debug Server for VS Code`.\n\nNote: you can only start the server once. You cannot stop it, at least from what I understand. If you run it again it'll just tell you it's already running and start the timer again to check for a confirmation.\n\n## Connecting the Editor\n\nOpen your addon folder (e.g. \"C:\\Code\\Blender Stuff\\addons\\myaddon\").\n\nInstall the Python extension for VS Code if you haven't already. For Visual Studio see [Installing Python Support](https://docs.microsoft.com/en-us/visualstudio/python/installing-python-support-in-visual-studio).\n\nIn the lower left ([see #3 here](https://code.visualstudio.com/docs/python/python-tutorial#_prerequisites)), VS Code should have auto detected your Python install and set it as the interpreter. For Visual Studio see [Managing Python Environments](https://docs.microsoft.com/en-us/visualstudio/python/managing-python-environments-in-visual-studio).\n\nGo to the Debugging tab and add a configuration. Pick Python. You'll want the configuration that looks like this, no need to change the defaults, you can delete the rest.\n\n```JSON\n\t{\n\t\t\"name\": \"Python: Attach\",\n\t\t\"type\": \"python\",\n\t\t\"request\": \"attach\",\n\t\t\"port\": 5678, //careful, this used to be 3000 in older versions of vscode and this addon\n\t\t\"host\": \"localhost\"\n\t},\n```\n\nNow when you run the debugger with this config in Blender and VS Code the console should print \"Debugger is Attached\" if it was still waiting (it should still attach even if it wasn't, it just won't tell you).\n\n## How to Use\n\nAt this point you should be able to add a breakpoint and when you trigger it in Blender, Blender should freeze and VS Code should pause on the breakpoint.\n\nNote though that if you make changes to the file, Blender will not detect them. Have open `User Preferences \u003e Addons` so you can toggle your addon on and off when you make changes. If anyone knows any way to improve this I'd love to know.\n\n## Advanced Usage\n\n### Wait for Client\n\nThe debugger can be made to wait for a client to connect (this will pause all execution). This can be useful for debugging the connection or when running blender headless / in background mode.\n\nTo do so, call the server connect command from the python console or from a script/addon like so:\n\n```python\nbpy.ops.debug.connect_debugger_vscode(waitForClient=True)\n```\n\n#### Running in Headless Mode\n\nFirst make sure the addon is installed, enabled, and works when you run blender normally.\n\nBlender can then be run in background mode with the `-b/--background` switch (e.g. `blender --background`, `blender --background --python your_script.py`).\n\nSee [Blender Command Line](https://docs.blender.org/manual/en/latest/advanced/command_line/introduction.html).\n\nYou can detect when blender is run in background/headless mode and make the debugger pause and wait for a connection in your script/addon:\n\n```python\nif bpy.app.background:\n\tbpy.ops.debug.connect_debugger_vscode(waitForClient=True)\n```\n\nThis will wait for a connection to be made to the debugging server. Once this is established, the script will continue executing and VSCode should pause on breakpoints that have been triggered.\n\nFor addons, you will need to do this from a handler:\n\n```python\nfrom bpy.app.handlers import persistent\n#...\ndef register():\n   bpy.app.handlers.load_post.append(load_handler)\n#...\n@persistent\ndef load_handler(dummy):\n\t# remove handler so it only runs once\n   bpy.app.handlers.load_post.remove(load_handler)\n   if bpy.app.background:\n      bpy.ops.debug.connect_debugger_vscode(waitForClient=True)\n\n```\nSee [Application Handlers](https://docs.blender.org/api/current/bpy.app.handlers.html)\n\n### Debugging/Editing Source Code\n\nIt is possible to edit the Blender source code but it can be a bit tricky to get it to detect changes (nevermind live editing is buggy anyways).\n\nFrom blender you can right click just about anything and click \"Edit Source\" to get it in the text editor. Then to find the path of the file, go to `Text \u003e Save As` and copy it from there.\n\nOpen the file in VS Code, connect to the debugging server, make a change and save it.\n\nNow in Blender the text editor will show this little red button in the top left. Click that and reload the file. Then in `Text Editor \u003e Properties` turn on `Live Edit` if you haven't already. Now to actually get Blender to detect any changes you made just type a single character (like add a space anywhere) and *then* it will detect your changes.\n\n### Debugging/Editing Scripts\n\n\tSee [Issue #4](https://github.com/AlansCodeLog/blender-debugger-for-vscode/issues/4) for a workaround.\n\tIn the future if I have some time, I might see if there's something I can do to make this easier.\n\n# Troubleshooting\n\n- Check you installed the correct debugpy version. With VS Code this should no longer be an issue, but I believe different versions of Visual Studio need different versions of debugpy (see [Installing Python Support](https://docs.microsoft.com/en-us/visualstudio/python/installing-python-support-in-visual-studio)).\n- To determine whether the problem is on Blender's side or your editor's: Close Blender and this [test script](https://github.com/AlansCodeLog/blender-debugger-for-vscode/blob/master/test.py), you can copy/download it or run it from the addon folder. Run it with Python `python test.py`, and then try to connect to the server with your editor. If you're still getting problems then the problem is with VS Code, try:\n\t\t- Check your detected your Python install, or set it manually.\n\t\t- For VS Code try reinstalling the VS Code Python extension.\n- If you've been using this addon for a while and it's suddenly giving you a connection error, it might be because the default port has changed. VS Code's Python extension (vscode-python) has changed their default port from 3000 to 5678, so I have changed the default accordingly. I've made it configurable now though, so just check the port the addon is set to matches the one in your `launch.json` in VS Code.\n\nOtherwise, if none of that helped, don't hesitate to file an issue.\n\n# Notes\n\n\u003ca id=\"f1\" href=\"#n1\"\u003e1.\u003c/a\u003e Technically, the add-on will work with Python 2 as well since it doesn't use Python itself, just the debupy package, so it doesn't really matter whether you installed it with Python 2 or 3 because the package is compatible with both. On the VS Code side though, the Python extension does need to know where Python is (though not debugpy), but it will still connect if it's using Python 2, but your IntelliSense recommendations will be wrong in VS Code.\n\n\u003ca id=\"f2\" href=\"#n2\"\u003e2.\u003c/a\u003e The addon also detects python if PYTHONPATH is set (because Blender will add it to sys.path) or if you used the Python bundled with Blender to install debugpy (but that's a bit of a pain because it doesn't have pip installed, you would have to install it manually).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlansCodeLog%2Fblender-debugger-for-vscode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAlansCodeLog%2Fblender-debugger-for-vscode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlansCodeLog%2Fblender-debugger-for-vscode/lists"}