Skip to content

Instantly share code, notes, and snippets.

@AsgerPetersen

AsgerPetersen/notes.md

Last active March 28, 2025 18:31
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save AsgerPetersen/9ea79ae4139f4977c31dd6ede2297f90 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save AsgerPetersen/9ea79ae4139f4977c31dd6ede2297f90 to your computer and use it in GitHub Desktop.
Download ZIP
Debugging QGIS 3.x python plugins on OSX using VS Code
Raw
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.

@PeterPetrik
Copy link

PeterPetrik commented Mar 13, 2019

Have you tried https://plugins.qgis.org/plugins/firstaid/ ?

@AsgerPetersen
Copy link
Author

AsgerPetersen commented Mar 13, 2019

@PeterPetrik yes, I have used firstaid since it came out. It is great for quickly exploring a problem. But when when the session involves editing of files I tend to prefer to have everything in a "real" editor with all the familiar functionality.

@stelf
Copy link

stelf commented May 7, 2019 •
edited
Loading

@AsgerPetersen after connecting the VSCode to QGIS, how do you manage to open the workspace - are you using the root of QGIS, or the plugin directory.

p.s. maybe is worth commiting these notes within the debugvs repo somewhere...

@AsgerPetersen
Copy link
Author

AsgerPetersen commented May 9, 2019

@stelf

In VSCode:

  1. I open the plugin code directory. This could for instance be /Users/asger/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/timemanager

  2. Select a Python interpreter. I have not found a way to select the interpreter used in QGIS, so I just select a generic python3 interpreter.

  3. In Debug panel click Add Configuration... in the configuration drop down.

  4. When VSCode Asks for an Environment select Python.

  5. Then VSCode shows a Select a debug configuration dropdown where you select Remote Attach.

  6. VSCode asks for a host name. Just use localhost

  7. Lastly you are asked for a port number. Use 5678. Now VSCode should have a Python: Remote Attach option in the debug configurations drop down .

  8. You need to change the pathMappings in the configuration manually. Click the cogwheel next to the configurations drop down and edit the pathMappings like described above.

In QGIS

Open QGIS and activate TimeManager plugin. Click the debugvs button.

Back in VSCode

In VSCode select Python: Remote Attach option in the debug configurations drop down and click the "play" button next to it.

Now your debugger should be attached to QGIS.

@dmcarvalho
Copy link

dmcarvalho commented May 22, 2019

Hi @AsgerPetersen, thanks a lot for your work!

@davidlgalt
Copy link

davidlgalt commented Aug 30, 2019

Thanks so much for this. I am having difficulty getting this to work with QGIS 3.8, as some file locations have changed and maybe there's just some things I am not getting.

Would the folder: C:\OSGeo4W64\apps\qgis\python\ be the one to put PTVSD into? Any other recommendations? Perhaps I should revert back to 3.6?

@veuncent
Copy link

veuncent commented Oct 11, 2019 •
edited
Loading

Instead of using the third-party Qgis plugin Enable Debug for Visual Studio it is also possible to attach the debugger in your own plugin (so you have more control over e.g. the version of ptvsd used).

I did this:

import sys
import traceback
from qgis.core import QgsMessageLog, Qgis


MESSAGE_CATEGORY = 'Messages'


def enable_remote_debugging():
    try:
        import ptvsd
        if ptvsd.is_attached():
            QgsMessageLog.logMessage("Remote Debug for Visual Studio is already active", MESSAGE_CATEGORY, Qgis.Info)
            return
        ptvsd.enable_attach(address=('localhost', 5678))
        QgsMessageLog.logMessage("Attached remote Debug for Visual Studio", MESSAGE_CATEGORY, Qgis.Info)
    except Exception as e:
        exc_type, exc_value, exc_traceback = sys.exc_info()
        format_exception = traceback.format_exception(exc_type, exc_value, exc_traceback)
        QgsMessageLog.logMessage(repr(format_exception[0]), MESSAGE_CATEGORY, Qgis.Critical)
        QgsMessageLog.logMessage(repr(format_exception[1]), MESSAGE_CATEGORY, Qgis.Critical)
        QgsMessageLog.logMessage(repr(format_exception[2]), MESSAGE_CATEGORY, Qgis.Critical)
 
 class MyQgisPlugin:
  def __init__(self, iface):
    enable_remote_debugging()
    # ... the rest of your plugin code

I wrote it down here.

@fedesanchez
Copy link

fedesanchez commented Oct 24, 2019

It works very well, is there any way to avoid having to close and reopen qgis every time I change the code?

@AsgerPetersen
Copy link
Author

AsgerPetersen commented Oct 24, 2019

@fedesanchez If you are debugging a plugin you can reload the plugin only using the “Plugin reloader” plugin. Otherwise I don’t know.

@Gaetanbrl
Copy link

Gaetanbrl commented Oct 8, 2020 •
edited
Loading

Hi, I have followed the advices :

  • Install ptvsd from Qgis 3.10 python env :
    C:\PROGRA~1\QGIS 3.10\apps\Python37>pip install ptvsd==4.1.4

  • Install debugvs plugin

  • Identify plugin folder :
    C:\Users\my_user\Documents\git\QgisCadastrePlugin\cadastre

  • Open this plugin folder with VS Code (right click + open with code)

  • Select python 3.7 from Qgis
    image

  • Create new debug launch.json file like that :

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Attacher",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "${workspaceFolder}"
                }
            ]
        }
    ]
}
  • I open QGIS and activate Cadastre plugin. Click the debugvs button ang i get this error :

image

  • If i directly execute the only one command from debugvs code from Qgis python37 i get an error :
C:\PROGRA~1\QGIS 3.10\apps\Python37>python.exe
Python 3.7.0 (v3.7.0:1bf9cc5093, Jun 27 2018, 04:59:51) [MSC v.1914 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import ptvsd
>>> ptvsd.enable_attach( address = ( 'localhost', 5678 ) )
>>>

I get no error and VScode seems to be in debug mode with workspace but i breakpoint are totally useless.. no effet.

Do you know this error ?

@Gaetanbrl
Copy link

Gaetanbrl commented Oct 8, 2020 •
edited
Loading

If we bypass debugvs plugin and directly use Qgis python console, we could see python info into VScode DEBUG CONSOLE 👍
image

But breakpoint doesn't work !

@stelf
Copy link

stelf commented Nov 6, 2020

@AsgerPetersen much appreciated!

@NicolaiLolansen
Copy link

NicolaiLolansen commented Feb 17, 2021 •
edited
Loading

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

@AsgerPetersen
Copy link
Author

AsgerPetersen commented Feb 17, 2021

Thank you @NicolaiMogensen

@kannes
Copy link

kannes commented Mar 1, 2021 •
edited
Loading

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.

@kannes
Copy link

kannes commented Mar 1, 2021 •
edited
Loading

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.

@FelixITA
Copy link

FelixITA commented Aug 14, 2023

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?

@stelf
Copy link

stelf commented Aug 23, 2023

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

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

@kannes
Copy link

kannes commented Aug 25, 2023

@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.

@stelf
Copy link

stelf commented Aug 25, 2023

@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.

@staffordsmith83
Copy link

staffordsmith83 commented Oct 25, 2023

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)

@pktrigg
Copy link

pktrigg commented Jan 14, 2024 •
edited
Loading

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.

@mariochermes
Copy link

mariochermes commented Feb 4, 2024 •
edited
Loading

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')
  1. Reload the plugin (or QGIS altogether), it should work now.

@pktrigg
Copy link

pktrigg commented Feb 4, 2024 via email

@rhinejoel
Copy link

rhinejoel commented Feb 13, 2024 •
edited
Loading

@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')
  1. 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

Screenshot 2024-02-13 at 4 55 09 PM

@rhinejoel
Copy link

rhinejoel commented Feb 16, 2024

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!

@sanak
Copy link

sanak commented Apr 27, 2024

@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

@stelf
Copy link

stelf commented Mar 21, 2025 •
edited
Loading

so update for everyone again struggling (as myself) to connect to debug plugins in March 2025 to the ... present version of QGIS 3.40.something.

as you can see below this is not conda, no venv, no fancy stuff, just straight system config, as qgis comes with its own python anyway. my install is the OSGeo4W install, though pretty sure this should work with other stripped-down versions.

contrary to what it was in 2019, now vscode-hosted debugging is possible solely with debugpy and this is the prolog which goes in init.py for my plugins

import debugpy

sys.path.append( 'C:\\Users\\strix\\.vscode\\extensions\\ms-python.python-2025.3.2025031701-win32-x64\\python_files\\lib\\python\\')

def setup_debugging():
    # Configure Python interpreter
    python_path = shutil.which("python")
    if not python_path:
        python_path = re.sub(r'[^/\\]+(?:\.exe)?$', 'python', sys.executable)

    # Print current environment for debugging
    print(f"Current directory   : {os.getcwd()}")
    print(f"Module path         : {__file__}")
    print(f"sys.executable      : {sys.executable}")
    print(f"devised python path : {python_path}")
    print(f"Python on PATH      : {shutil.which("python")}")
    
    try:
        # This can help if you're running different Python versions
        # Cross-platform method to replace executable with python
        debugpy.configure(python=python_path)

        print("try to listen")
        try:
            debugpy.listen(("localhost", 5678))
            print("Debugpy server started, waiting for connection...")
            # debugpy.wait_for_client()
            print("Debugger connected!")
        except Exception as e:
            # If listening fails, try to connect (client mode)
            print(f"Couldn't start debugpy server: {e}")
            print("Trying to connect as client...")
            debugpy.connect(("localhost", 5678))
            print("Connected to debugpy server!")
    except Exception as e:
        print(f"Debugpy error: {e}")

notes:

  • debugpy.wait_for_client() is grayed out as it causes basically causes QGIS to reload. At one point it was like a fork bomb actually, very vad. I thought the python path was the issue initially, perhaps is not. Others also complain, I could find some cries for help on various forums. So if you want to wait for your debugger, perhaps another logic should be implemented, thing is it WORKS as it is now, given the plugin compiles and imports modules properly, and then you can async connect to the debugpy which is alredy working in some separate light interpreter thread I guess (not sure the mechanics though).
  • strix here is some generic user, and your version of vscode plugins dir may differ. i'm absolute not convinced you actually need this.
  • the setup checks for already connected debugger. this presumes you can reload (CTRL-F5) your plugin with the excellent Plugin Re-loader plugin
  • you can install debugpy from the python console in QGIS, or via the OSGeo4W, I trust you know how to do it .
  • dubgvs is not needed anymore as plugin

the struggle, hence the length of this setup_debugging, was to map the dev dir to the qgis dir. not sure how you guys develop, but I have the code in separate dir from the plugins dir, and neither I use the additional plugin dirs feature. Claude created for me a deploy script such that it watches over files and copies those modified to the plugin dir (on windows one also has to explicitly allow this, as c:\Program Files\ is protected... perhaps my setup is a bit unpopular one, but works OK for me).

I spent like a day remembering how exactly this mapping thing should normally be, and eventually ended with this launch.json

    "configurations": [
        {
            "name": "Python: Remote Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/",
                    "remoteRoot": "C:\\PROGRA~1\\QGIS34~1.4\\apps\\qgis-ltr\\python\\plugins\\"
                },
            ],
            "justMyCode": false
        },

Here, localRoot typically equals to your current dir, the project dir. The remoteRoot changes depending on where you deploy (or if you have had QGIS load plugin directly from the dev dir). I decided to not try to set it automatically, though is perhaps possible with some prerun script to get the QGIS location for the user (and unless, again he has 3 different versions like myself). Most tutorials have you set remoteRoot to the same dir as localRoot which should (havent tested it) work when you develop and load/run the plugin from one and the same dir.

Also make sure that you've set the python compiler for pylance to work properly and the extraPaths. here's a Qt5 config that works

{
  "python.analysis.extraPaths": [
    "C:\\Program Files\\QGIS 3.40.4\\apps\\Python312",
    "C:\\Program Files\\QGIS 3.40.4\\apps\\Python312\\Lib\\site-packages",
    "C:\\Program Files\\QGIS 3.40.4\\apps\\qgis-ltr\\python",
    "C:\\Users\\strix\\.vscode\\extensions\\ms-python.python-2025.3.2025031001-win32-x64\\python_files\\lib\\python\\"
  ],
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.diagnosticMode": "workspace",
  "python.analysis.include": [
    "c:/Work/fmigis/apify"
  ],
  "python.analysis.diagnosticSeverityOverrides": {
    "reportOptionalMemberAccess": "none"
  },
  "python.languageServer": "Pylance",
  "python.analysis.autoImportCompletions": true,
  "python.analysis.indexing": true,
  "python.analysis.packageIndexDepths": [
    { "name": "qgis", "depth": 4,  "includeAllSymbols": true },
    { "name": "PyQt5", "depth": 4,  "includeAllSymbols": true }
  ]
}

for everyone reading this far, perhaps you should note that "c:/Work/fmigis/apify" in the example is the project homedir, so update this accordingly. this is basically the git project root. also these python.analysis directives were absolutely necessarily to get the linter read the correct dirs. also, the selected language server is pylance and the analysis is done by it, hence your linter may behave differently.

Note - it is very likely that this will not work with newer PyQt6 versions, still experimental at time of writing. QGIS devs introduced a compatibility layer, but I couldn't find a way to have all the linters understand its magic, thus my imports were littered with warnings which impact the dev process, and my progress respectively.

Good luck, and I may actually release the plugin I'm writing atm, I just needed to share findings once the vscode connected, as this obstacle really drove me crazy.

...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment