VSCode .env for developing plugins

terribletum · April 9, 2026, 5:35am

Hi there
Please is anyone able to provide dummy instructions to configure VSCode .env for developing QGIS plugins?
I want to be able to start VS Code and develop plugins against specific versions of QGIS and its associated Python environment, with code-completion / IntelliSense working for QGIS libraries. Looking for a solution that is repository specific.
This is different to the debugging described in 10.26. QGIS DevTools — debugging QGIS plugins — NextGIS 1.12 documentation.
Any advice or learnings welcome. Thanks

ekazakov · April 9, 2026, 7:17am

Hello Tim! Could you please specify the OS you use?

terribletum · April 9, 2026, 9:09am

oh - the obvious stuff… like i said, for dummies. I’m on Windows. Thanks.

ekazakov · April 9, 2026, 10:26am

It’s quite tricky to set up a proper environment in Windows, unfortunately, and we currently don’t have ready manual regarding this. I asked our developers to come up with something helpful, it could take a couple of days, I’ll keep you informed

terribletum · April 9, 2026, 8:33pm

Thx - it seems the fragments of info out there relate to legacy methods for debugging, now superseded by your chapter 10.26 above.
So for rich IDE experience it may now be a combination of .vscode folder with settings.json and launch.json (which links to .env?).
Any help/best practices will definitely be appreciated.

terribletum · April 14, 2026, 6:12am

I have made progress using VS Code workspace in conjunction with .vscode\settings.json
It’s looking like a clean solution with no .env files, no bat files, no messing with environment variables or QGIS settings. IntelliSense and code-complete are working and the dreaded red squiggly underlines have been resolved. I’ve written it up in a pdf but unable to attach in this thread so will email to admin.

i.barsukov · April 14, 2026, 4:17pm

Hello Tim,

I am a plugin developer at NextGIS. Developing on Windows always requires significant setup effort. Below is a practical guide for setting up a Windows environment for QGIS plugin development and debugging in VS Code.

What You Will Need

Install the following software:

The required version of QGIS via OSGeo4W
Visual Studio Code

When installing OSGeo4W, it is recommended to select the debugpy package right away.

VS Code Extensions

Install the following extensions in VS Code:

QGIS Plugins

Install the following plugins in QGIS:

First Aid
Overrides the default error handler in QGIS. It allows you to inspect the call stack and execute commands when an exception occurs.
Plugin Reloader
Lets you reload only the plugin after making changes, without restarting QGIS completely.
QGIS DevTools
Lets you start a debugpy debug server and connect to it from VS Code.

Configuring PyQt Autocompletion

To make PyQt class autocompletion work correctly in VS Code, you need to manually add the .pyi files.

1. Find Out the PyQt Version Used by QGIS

Open the Python Console in QGIS and run:

PYQT_VERSION_STR

This will return the PyQt version.

2. Download the Matching Wheel File

Find the required version in the PyQt5 release history:

https://pypi.org/project/PyQt5/#history

After selecting the version, open the Download files section and download the corresponding .whl archive.

For example:

PyQt5-5.15.11-cp38-abi3-win_amd64.whl

3. Extract the `.pyi` Files

A .whl file is a regular archive. You can unpack it using any archive tool, such as 7-Zip.

Inside the archive, locate the PyQt5 directory and copy all .pyi files from it.

4. Copy the `.pyi` Files into the Installed PyQt Package

Locate the PyQt5 directory in the OSGeo4W Python environment.

For example:

C:\OSGeo4W\apps\Python312\Lib\site-packages\PyQt5

Copy the extracted .pyi files there.

This will allow VS Code to properly suggest PyQt classes and methods.

Launching VS Code in the QGIS Environment

Create a file named vscode_qgis.bat with the following contents:

set OSGEO4W_ROOT=C:\OSGeo4W
set CODE_ROOT="C:\Program Files\Microsoft VS Code"

@echo off
call "%OSGEO4W_ROOT%\bin\o4w_env.bat"
@echo off
path %OSGEO4W_ROOT%\apps\qgis\bin;%CODE_ROOT%;%PATH%
set QGIS_PREFIX_PATH=%OSGEO4W_ROOT:\=/%/apps/qgis
set QT_PLUGIN_PATH=%OSGEO4W_ROOT%\apps\qgis\qtplugins;%OSGEO4W_ROOT%\apps\qt5\plugins
set PYTHONPATH=%OSGEO4W_ROOT%\apps\qgis\python;%PYTHONPATH%
code %*

Adjust the OSGEO4W_ROOT and CODE_ROOT values according to the paths on your system.

Then run vscode_qgis.bat. VS Code should open with the correct environment.

You can also configure the environment without using vscode_qgis.bat, relying only on local project settings (settings.json), but in our experience this approach is more sensitive to the surrounding environment and can sometimes lead to problems.

Selecting the Python Interpreter in VS Code

After launching VS Code, do the following:

Press Ctrl+Shift+P
Select Python: Select Interpreter
Click Enter interpreter path
Then select Find
Point to python.exe in the apps directory inside OSGeo4W

This is an important detail: the interpreter from bin usually does not work correctly in VS Code, so you should select the Python executable specifically from apps.

Example path:

C:\OSGeo4W\apps\Python312\python3.exe

Additional VS Code Settings

For convenience, you can configure file associations in settings.json:

"files.associations": {
  "metadata.txt": "ini",
  "*.ts": "xml",
  "*.ui": "xml"
}

After completing these steps, you will have a convenient environment for QGIS plugin development on Windows: with a working interpreter, PyQt autocompletion, the ability to quickly reload the plugin, and debugger integration with VS Code.

For convenience, you can also create a shortcut to vscode_qgis.bat, place it on the desktop, and assign it an icon.

terribletum · April 15, 2026, 10:35am

What an epic write up!
I’m working through it… much appreciated.

terribletum · April 16, 2026, 8:42am

Magic! Thrilled to have this working - thanks once again. My setup is a bit difererent and I’ve managed to work with settings.json in lieu of vcode_qgis.bat. For those that are interested:

Software

plain QGIS (I'll investigate OSGeo4W install later)
VS Code

debugpy

Because I don't have OSGeo4W to manage 3rd party packages,

run C:\Program Files\QGIS 3.40.15\OSGeo4W.bat as Admin

then python -m pip install debugpy

VS Code Extensions

as above

QGIS Plugins

as above

Configuring PyQt AutoCompletion

as above, with my setup these were copied to:

C:\Program Files\QGIS 3.40.15\apps\Python312\Lib\site-packages\PyQt5

VS Code and QGIS Environment with settings.json

For plugins, my repo is completely separate from QGIS install / QGIS profile/plugins. Key items in my repo are:

└─ repoFolder
├─ .vscode\

├─ settings.json
└─ launch.json

├─ repo.code-workspace
├─ pyproject.toml
├─ __init__.py
├─ plugin.py
├─ metadata.txt
└─ ...<any other files/folders as required for plugin>

repo.code-workspace (no extension) simply defines the current folder and all its contents as a workspace.

{
  "folders": [
    { "path": "." }
  ],
  "settings": {
    "python.languageServer": "Pylance"
  }
}

pyproject.toml required if using Ruff

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "W", "I"]

and settings.json is where the QGIS environment is defined (obviously adjust paths for your install):

{
  // --- Python interpreter used by Pylance ---
  "python.defaultInterpreterPath": "C:/Program Files/QGIS 3.40.15/apps/Python312/python.exe",
  // --- Make PyQGIS importable for IntelliSense ---
  "python.analysis.extraPaths": [
    "C:/Program Files/QGIS 3.40.15/apps/qgis-ltr/python",
    "C:/Program Files/QGIS 3.40.15/apps/qgis-ltr/python/qgis",
    "C:/Program Files/QGIS 3.40.15/apps/qgis-ltr/python/plugins"
  ],

  // --- Keep analysis sensible for plugin repos ---
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.diagnosticMode": "workspace",

  // formatting with ruff rather than AutoPep8
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports.ruff": "always",
      "source.fixAll.ruff": "always"
    }
  },
  "ruff.configurationPreference": "filesystemFirst",

  // --- Trim whitespace/newlines on save ---
  "files.trimTrailingWhitespace": true,
  "files.trimFinalNewlines": true,
  "files.insertFinalNewline": true,

  // --- Whitespace visibility + diff behaviour ---
  "editor.renderWhitespace": "trailing",
  "diffEditor.ignoreTrimWhitespace": false,

  // --- Basic hygiene ---
  "files.eol": "\n",
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  },
  "search.exclude": {
    "**/__pycache__": true
  }
}

Debugging Plugin

Start GIS and enable QGIS Dev Tools as per [10.26 QGIS DevTools - Debugging](https://docs.nextgis.com/docs_ngqgis/source/devtools.html?ref=ekazakov.me#qgis-devtools-settings)
Start debugger in QGIS and copy launch.json
Start VS Code normally (no bat file required) and File / Open workspace and select repo.code-workspace
Save launch.json in .vscode subfolder and confirm "remoteRoot" path. Note - this should be only required once per workspace setup.
Still in VS Code: Run & Debug: Attach to QGIS
Add breakpoints as required
Start doing stuff in QGIS to hit those breakpoints

Debugging script

Almost the same.... copy the following files from the plugin folder into the scripts folder:

repo.code-workspace (and helps if you rename as scripts.code-workspace)
.vsCode folder and contents (2 x json files)

Then:

Start QGIS
Plugins/python console/Show Editor/ then open script
Enable script debugging
Copy launch.json template
Start VS Code normally (no bat file required) and File / Open workspace and select scripts.code-workspace
overwrite contents of scripts\.vscode\launch.json (definition is a bit different to working with plugins) and save. This should be a one-time operation for this workspace.
Add breakpoints as required within VS Code IDE
Still in VSCode Run & Debug: Attach to QGIS
Start doing stuff in QGIS....

Cheers

VSCode .env for developing plugins

What You Will Need

VS Code Extensions

QGIS Plugins

Configuring PyQt Autocompletion

1. Find Out the PyQt Version Used by QGIS

2. Download the Matching Wheel File

3. Extract the .pyi Files

4. Copy the .pyi Files into the Installed PyQt Package

Launching VS Code in the QGIS Environment

Selecting the Python Interpreter in VS Code

Additional VS Code Settings

Software

debugpy

VS Code Extensions

QGIS Plugins

Configuring PyQt AutoCompletion

VS Code and QGIS Environment with settings.json

Debugging Plugin

Debugging script

3. Extract the `.pyi` Files

4. Copy the `.pyi` Files into the Installed PyQt Package