Debugging QGIS 3.x python plugins on OSX using VS Code

notes.md

Debugging QGIS 3.x python plugins on OSX using VS Code

Plugin

In QGIS install the plugin debugvs.

Python dependencies

The debugvs plugin needs the python module ptvsd to function. This module is not installed by default.

In principle you just pip install ptvsd in the python interpreter used by QGIS.

I am using the QGIS OSX installer from Lutra Consulting. This installer works really great, but installing additional python modules is not very easy.

What I did was this:

1. Download the ptvsd wheel from pypi. I tried with the newest version (4.2.4), but that didnt work for me. I ended up using ptvsd-4.1.4.zip.
2. Unzip the wheel (if it has the extension .whl then rename it to .zip)
3. Inside the zip there are two directories. Copy the directory ptvsd to the Resources/python of your QGIS installation. In my case this was /Applications/QGIS3.6.app/Contents/Resources/python/.

Restart QGIS.

Setting up VSCode

The default remote debugger configuration in VS Code looks like this

{
    "name": "Python: Remote Attach",
    "type": "python",
    "request": "attach",
    "port": 5678,
    "host": "localhost",
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "."
        }
    ]
},

I had to change the pathMappings to get it to work:

{
    "name": "Python: Remote Attach",
    "type": "python",
    "request": "attach",
    "port": 5678,
    "host": "localhost",
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "${workspaceFolder}"
        }
    ]
},

Debugging

• In QGIS click Plugins -> Enable Debug for Visual Studio -> Enable Debug for Visual Studio
• You should now see a message in the QGIS message bar saying something like DebugVS : Run the Debug in Visual Studio(Python:Attach)
• In VS Code start debugging using the Python: Remote Attach configuration defined above.

Now you should be able to set breakpoints in VS Code.

@AsgerPetersen much appreciated!

If anyone comes across this guide, and is using Windows, I have written a Windows guide following the same principles here:
https://gist.github.com/NicolaiLolansen/acfd8723720c4761aefef3cdfc2aa55a

Thank you @NicolaiMogensen

I had to change the pathMappings to get it to work:

probably meant that breakpoints did not work and the editor showed them greyed out with "Breakpoint in file that does not exist". At least that is what fixed that issue for me.

The JSON bits in the OP are just one configuration part of a launch.json, the whole launch.json might look like this if all you add is that one configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: attach",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "${workspaceFolder}"
                }
            ]
        }
    ]
}

You can NOT just have the one configuration part in the file, you need it nested and named like above. The editor will not give you any useful error message if that is not the case.

Qgis 3.32 (Lima) installed from Osgeo4w.
I followed instructions (install ptvsd then debugpy and installed plugin debugvs).
When I launch "Plugins->"Enable debug for Visual Studio" actually it:

• launches another qgis desktop giving this 8 errors:
  err 1. Invalid data source: C:\Users.......\stringofcodes is not a valid or recognize data source
  err 2. Invalid Data Source: C:\Users....\Documents--server-access-token is not valid or recognize data source
  err 3. the same with C:\Users....\Documents\5678
  err 4. the same with --port
  err 5. the same with localhost
  ...

Actually I don't know how to solve it. I tried also a fresh installation etc. always the same result.

Someone can suggest how to solve it or a workaround?

okay, here's a summary based on everyone's comments so far. (gpt-generated, but may become a part of the documentation after review)

Debugging QGIS 3.x Python Plugins on OSX using VS Code: A Comprehensive Guide

This guide is based on a gist by AsgerPetersen et al. and aims to provide a step-by-step walkthrough for debugging Python plugins in QGIS 3.x on OSX using Visual Studio Code.

---

Table of Contents

1. Installing the Plugin
2. Setting Up Python Dependencies
3. Configuring VS Code
4. Debugging in QGIS

---

Installing the Plugin

1. Open QGIS.
2. Navigate to the plugin manager and search for debugvs.
3. Install the plugin.

---

Setting Up Python Dependencies

The debugvs plugin requires the Python module ptvsd. Here's how to install it:

1. Download the ptvsd wheel from PyPI. It's recommended to use version 4.1.4.
2. Unzip the wheel file (rename .whl to .zip if needed).
3. Inside the unzipped folder, locate the ptvsd directory.
4. Copy this directory to the Resources/python folder of your QGIS installation. For example, /Applications/QGIS3.6.app/Contents/Resources/python/.
5. Restart QGIS to apply the changes.

---

Configuring VS Code

The default remote debugger configuration in VS Code needs to be modified:

1. Open your project in VS Code.
2. Navigate to the debugging section and locate the launch.json file.
3. Find the configuration named Python: Remote Attach and modify the pathMappings as follows:

{
  "name": "Python: Remote Attach",
  "type": "python",
  "request": "attach",
  "port": 5678,
  "host": "localhost",
  "pathMappings": [
    {
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "${workspaceFolder}"
    }
  ]
}

---

Debugging in QGIS

1. Open QGIS and go to Plugins -> Enable Debug for Visual Studio -> Enable Debug for Visual Studio.
2. A message should appear in the QGIS message bar, indicating that debugging is enabled.
3. Switch to VS Code and start debugging using the Python: Remote Attach configuration.
4. You can now set breakpoints and debug your Python plugins in QGIS.

---

Additional Resources

• Original Gist by AsgerPetersen
• QGIS Plugins

Feel free to follow this guide to make your debugging process in QGIS smoother and more efficient. Happy coding!

@stelf did you check that this summary is accurately summarizing the findings in this comment section and the best practice? E.g. why does it specify the host and port not nested in a connect section like shown on https://code.visualstudio.com/docs/python/debugging ?

My initial reaction is: Please don't pollute the web with low quality "AI" generated content.

@kannes yeah I was really hoping to see some reaction. sorry if you found it offensive, I can delete the comment. point was made that this is something that may be suitable for the documentation. btw - the AI generated content is perhaps inevitable, as much as plastic pollution is.

I get this error when trying to enable the plugin in VSCode:

cannot import name 'absolute_path' from 'pydevd_file_utils' (/Applications/QGIS.app/Contents/Resources/python/ptvsd/_vendored/pydevd/pydevd_file_utils.py)

I followed the instructions above.
Mac OSX v13.5.2
QGIS 3.30.2

ptvsd v4.3.2 (cannot find a wheel for 4.1.4 anymore)

Qgis 3.32 (Lima) installed from Osgeo4w. I followed instructions (install ptvsd then debugpy and installed plugin debugvs). When I launch "Plugins->"Enable debug for Visual Studio" actually it:

• launches another qgis desktop giving this 8 errors:
  err 1. Invalid data source: C:\Users.......\stringofcodes is not a valid or recognize data source
  err 2. Invalid Data Source: C:\Users....\Documents--server-access-token is not valid or recognize data source
  err 3. the same with C:\Users....\Documents\5678
  err 4. the same with --port
  err 5. the same with localhost
  ...

Actually I don't know how to solve it. I tried also a fresh installation etc. always the same result.

Someone can suggest how to solve it or a workaround?

Hi
I get the same 8 errors when I start the debug plugin. It also opens a new instance of qgis. I have been fighting this all day without luck.
am using qgis 3.34.1 on windows 10
as far as I know we dont need to install pvtsd with the current version of the plugin. either way we get the same 8 errors here.

2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\AppData\Roaming\Python\Python39\site-packages\debugpy\adapter is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--for-server is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\49899 is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--host is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\localhost is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--port is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\5678 is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--server-access-token is not a valid or recognized data source.
2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\b8f00babbe3d5c52c125545fafdad7f044eaa73b1ecac8671d6c01aa3d6bd75c is not a valid or recognized data source.
2024-01-14T18:48:47 WARNING Python error : An error has occurred while executing Python code: See message log (Python Error) for more details.

Qgis 3.32 (Lima) installed from Osgeo4w. I followed instructions (install ptvsd then debugpy and installed plugin debugvs). When I launch "Plugins->"Enable debug for Visual Studio" actually it:

• launches another qgis desktop giving this 8 errors:
  err 1. Invalid data source: C:\Users.......\stringofcodes is not a valid or recognize data source
  err 2. Invalid Data Source: C:\Users....\Documents--server-access-token is not valid or recognize data source
  err 3. the same with C:\Users....\Documents\5678
  err 4. the same with --port
  err 5. the same with localhost
  ...

Actually I don't know how to solve it. I tried also a fresh installation etc. always the same result.
Someone can suggest how to solve it or a workaround?

Hi I get the same 8 errors when I start the debug plugin. It also opens a new instance of qgis. I have been fighting this all day without luck. am using qgis 3.34.1 on windows 10 as far as I know we dont need to install pvtsd with the current version of the plugin. either way we get the same 8 errors here.

2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\AppData\Roaming\Python\Python39\site-packages\debugpy\adapter is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--for-server is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\49899 is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--host is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\localhost is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--port is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\5678 is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--server-access-token is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\b8f00babbe3d5c52c125545fafdad7f044eaa73b1ecac8671d6c01aa3d6bd75c is not a valid or recognized data source. 2024-01-14T18:48:47 WARNING Python error : An error has occurred while executing Python code: See message log (Python Error) for more details.

@pktrigg I don't know if you were able to solve this. But here is how I did it:

1. Find your QGIS plugins folder, it generally is somewhere like:
   C:\Users\user\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins
2. Look for debug_vs and open it's init.py file.
3. Where debugpy is imported, add the line: self.debugpy.configure(python = 'python3')
   The result should look something like this:

        import debugpy

        self.debugpy = debugpy
        self.debugpy.configure(python = 'python3')

4. Reload the plugin (or QGIS altogether), it should work now.

Thank Mario I tried this and I can now debug on my main machine. Still need to sort it on my laptop and cannot see the difference but I am sure I will get there! Once again thanks you From: Mário Hermes ***@***.***> Sent: Sunday, February 4, 2024 8:10 AM To: mariochermes ***@***.***> Cc: Comment ***@***.***> Subject: Re: AsgerPetersen/notes.md @mariochermes commented on this gist.

…

________________________________ Qgis 3.32 (Lima) installed from Osgeo4w. I followed instructions (install ptvsd then debugpy and installed plugin debugvs). When I launch "Plugins->"Enable debug for Visual Studio" actually it: * launches another qgis desktop giving this 8 errors: err 1. Invalid data source: C:\Users.......\stringofcodes is not a valid or recognize data source err 2. Invalid Data Source: C:\Users....\Documents--server-access-token is not valid or recognize data source err 3. the same with C:\Users....\Documents\5678 err 4. the same with --port err 5. the same with localhost ... Actually I don't know how to solve it. I tried also a fresh installation etc. always the same result. Someone can suggest how to solve it or a workaround? Hi I get the same 8 errors when I start the debug plugin. It also opens a new instance of qgis. I have been fighting this all day without luck. am using qgis 3.34.1 on windows 10 as far as I know we dont need to install pvtsd with the current version of the plugin. either way we get the same 8 errors here. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\AppData\Roaming\Python\Python39\site-packages\debugpy\adapter is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--for-server is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\49899 is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--host is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\localhost is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--port is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\5678 is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents--server-access-token is not a valid or recognized data source. 2024-01-14T18:44:30 CRITICAL Invalid Data Source : C:\Users\Operator\Documents\b8f00babbe3d5c52c125545fafdad7f044eaa73b1ecac8671d6c01aa3d6bd75c is not a valid or recognized data source. 2024-01-14T18:48:47 WARNING Python error : An error has occurred while executing Python code: See message log (Python Error) for more details. I don't know if you were able to solve this. But here is how I did it: 1. Find your QGIS plugins folder, it generally is somewhere like: C:\Users{user}\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins 2. Look for debug_vs and open it's init.py file. 3. Where debugpy is imported, add the line: self.debugpy.configure(python = 'python3') The result should look something like this: import debugpy self.debugpy = debugpy self.debugpy.configure(python = 'python3') 1. Reload the plugin (or QGIS altogether), it should work now. — Reply to this email directly, view it on GitHub<https://gist.github.com/AsgerPetersen/9ea79ae4139f4977c31dd6ede2297f90#gistcomment-4873230> or unsubscribe<https://github.com/notifications/unsubscribe-auth/ACDTJMMMFBNJXG2L6GTDPSDYR3GUJBFKMF2HI4TJMJ2XIZLTSKBKK5TBNR2WLJDUOJ2WLJDOMFWWLO3UNBZGKYLEL5YGC4TUNFRWS4DBNZ2F6YLDORUXM2LUPGBKK5TBNR2WLJDHNFZXJJDOMFWWLK3UNBZGKYLEL52HS4DFVRZXKYTKMVRXIX3UPFYGLK2HNFZXIQ3PNVWWK3TUUZ2G64DJMNZZDAVEOR4XAZNEM5UXG5FFOZQWY5LFVA4TKMBYGM2TMMFHORZGSZ3HMVZKMY3SMVQXIZI>. You are receiving this email because you commented on the thread. Triage notifications on the go with GitHub Mobile for iOS<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android<https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

@pktrigg I don't know if you were able to solve this. But here is how I did it:

1. Find your QGIS plugins folder, it generally is somewhere like:
   C:\Users\user\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins
2. Look for debug_vs and open it's init.py file.
3. Where debugpy is imported, add the line: self.debugpy.configure(python = 'python3')
   The result should look something like this:

        import debugpy

        self.debugpy = debugpy
        self.debugpy.configure(python = 'python3')

4. Reload the plugin (or QGIS altogether), it should work now.

@AsgerPetersen
@mariochermes I did that and resolved the 8 errors as well as the 2nd instance of QGIS. However, this persists.

RuntimeError: timed out waiting for adapter to connect

macOS 14.1.2
QGIS 3.34

Hi, from another post I realized that I needed to specify the python interpreter path in debugpy.configure() thus following this thread,

debugpy.configure(python=r"path_to_qgis_python_")
debugpy.listen(...)

I am now able to launch the server and connect via VS Code. Thank you!

@rhinejoel
Thanks for the useful information!
Above path_to_qgis_python_ part was important in my case (using official download version (qgis-mac-ltr.dmg)), because specifying only python3 uses another system python (/Applications/Xcode.app/Contents/Developer/Library/Frameworks/Python3.framework/Versions/3.9/Resources/Python.app/Contents/Python).
The following works on my environment.

@@ -48,6 +48,8 @@
             import debugpy
 
             self.debugpy = debugpy
+            self.debugpy.configure(python=r"/Applications/QGIS.app/Contents/MacOS/bin/python3")
+            self.debugpy.listen(...)
         except:
             pass
         self.port = 5678