How to Install QGIS Python Bindings on Windows

The fastest and officially supported way to install QGIS Python bindings on Windows is the OSGeo4W Network Installer. It resolves the compiled C++ dependencies, registers the environment variables PyQGIS needs, and links qgis.core and qgis.gui to a managed Python runtime. Do not run pip install pyqgis — the PyPI package is a documentation stub with none of the Windows binaries the real bindings require.

This is the Windows companion to the interactive workflow covered in the parent QGIS Python Console Basics guide. Inside QGIS the console already injects the correct PYTHONPATH for you; the goal here is to make the same qgis modules importable from an external interpreter so you can run scripts, IDEs, and automation outside the desktop. If you only want to script from within QGIS, you already have the bindings and can skip to the console guide.

Choosing a Windows PyQGIS install pathStart by asking whether you need PyQGIS to run outside QGIS Desktop. If no, the built-in Python Console already loads the bindings and nothing is installed. If yes, take Method 1, the OSGeo4W Network Installer, which auto-registers QGIS_PREFIX_PATH, PYTHONPATH and PATH, or Method 2, the Standalone Installer, where you set the paths yourself through a run_pyqgis.bat launcher. Both methods converge on a working import of qgis.core with QgsApplication initializing and data providers loaded.Two Windows install paths — both end at a working importDo you need PyQGIS to runoutside QGIS Desktop?NOYESNothing to installThe built-in PythonConsole already loadsqgis.coreMethod 1 · OSGeo4WNetwork InstallerAuto-registersQGIS_PREFIX_PATH,PYTHONPATH, PATHMethod 2 · StandaloneInstallerYou set paths viarun_pyqgis.bat(per session)import qgis.core ✓QgsApplication starts, data providers load

Prerequisites

Confirm each of these before installing — most "it won't import" reports on Windows trace back to a mismatch in this list rather than a broken install:

  • OS: Windows 10/11 64-bit only (32-bit was deprecated in QGIS 3.20).
  • QGIS version: 3.44 LTR (recommended) or 4.0+ current.
  • Python version: whatever ships with your QGIS — 3.12 for QGIS 3.34 and later (including 3.44 LTR); older releases such as 3.28 LTR bundled 3.9. You cannot substitute a separately installed Python.
  • Architecture: strictly 64-bit throughout. Mixing a 32-bit Python with 64-bit QGIS DLLs raises ImportError on the first import qgis.core.
  • Permissions: administrator rights are needed only when the installer writes machine-level PATH / PYTHONPATH entries. A per-session launcher works without elevation.
  • Environment conflicts: a standalone Anaconda/Miniconda base environment on the PATH frequently shadows the QGIS libraries. Keep conda deactivated, or isolate work in a dedicated environment as described in Virtual Environments for GIS.

The OSGeo4W installer is the path that requires no manual path surgery — it wires up the environment for you.

  1. Download the OSGeo4W Network Installer (64-bit) from the official QGIS download page.
  2. Run it, choose Install from Internet, and accept the default root (C:\OSGeo4W). Avoid spaces or special characters anywhere in the install path — they break several downstream scripts.
  3. In the package selection screen, expand Desktop and check qgis-ltr (recommended) or qgis.
  4. Expand Libs → Python and verify python3-qgis and python3-qgis-common are selected. Dependencies such as gdal-python and numpy auto-select.
  5. Complete the install. OSGeo4W registers QGIS_PREFIX_PATH and PYTHONPATH and prepends the QGIS bin directories to your PATH.

Verify the bindings

Launch the QGIS-managed Python shell so system Python cannot interfere:

C:\OSGeo4W\bin\python-qgis-ltr.bat

Then run this headless verification script. It initializes a full standalone QgsApplication — the same bootstrap every off-desktop script uses — and creates a throwaway memory layer to prove the data providers loaded:

import qgis.core
from qgis.core import QgsApplication

print(f"PyQGIS loaded: {qgis.core.Qgis.QGIS_VERSION}")

# Match your installation type: qgis-ltr or qgis
QgsApplication.setPrefixPath("C:/OSGeo4W/apps/qgis-ltr", True)
qgs = QgsApplication([], False)
qgs.initQgis()

layer = qgis.core.QgsVectorLayer("Point", "temp", "memory")
print(f"Test layer valid: {layer.isValid()}")

qgs.exitQgis()

If both lines print and the layer reports valid, module resolution and the GDAL/OGR providers are working. From here you can point an IDE at the same interpreter — see setting up PyCharm for QGIS development for the interpreter and environment-variable configuration.

Method 2: Standalone Installer (manual configuration)

If corporate firewalls block the OSGeo4W package repository, use the official QGIS Windows Standalone Installer instead. It does not auto-register Python paths, so you supply them yourself through a launcher.

  1. Install the standalone package (default: C:\Program Files\QGIS 3.44).
  2. Create a session launcher, run_pyqgis.bat:
@echo off
set "QGIS_ROOT=C:\Program Files\QGIS 3.44"
set "PATH=%QGIS_ROOT%\bin;%QGIS_ROOT%\apps\qgis\bin;%PATH%"
set "PYTHONPATH=%QGIS_ROOT%\apps\qgis\python;%QGIS_ROOT%\apps\qgis\python\plugins;%PYTHONPATH%"
set "QGIS_PREFIX_PATH=%QGIS_ROOT%\apps\qgis"
set "PYTHONHOME=%QGIS_ROOT%\apps\Python312"
"%QGIS_ROOT%\bin\python3.exe"
  1. Double-click the batch file. It opens a terminal with PyQGIS importable for that session only, leaving machine-wide settings untouched. If your build ships a different Python, change Python312 to match the folder under apps\, and swap qgis for qgis-ltr in the paths if you installed the LTR variant. Run the same verification script above to confirm.

What the two installers actually give you

The choice between them is not about ease of installation but about whether you will ever need to add a package or run a script outside the application.

OSGeo4W versus the standalone installerThe network installer provides a package manager, allows several QGIS versions side by side, ships environment scripts that configure paths, and suits development. The standalone installer is a single fixed bundle with no package manager, one version at a time, and manual environment configuration, and suits a desktop user who will never script.Pick by what you will do next, not by download sizecapabilityOSGeo4Wstandaloneadd Python packages✓ package managermanual pip onlyseveral QGIS versions✓ side by sideone at a timeenvironment scripts✓ o4w_env.batset the vars yourselfsuitsdevelopmentdesktop use onlychoose OSGeo4W if any PyQGIS is in your future

The environment variables that matter

Four variables have to be right before the bindings will import, and the OSGeo4W shell sets all four for you — which is precisely why it is the recommended route.

The four variables the bindings needPYTHONPATH points at the QGIS python directory so the modules can be found. PATH points at the bin directory so the compiled libraries load. QGIS_PREFIX_PATH tells QGIS where its resources live. GDAL_DATA points at the projection and format definitions. The OSGeo4W shell sets all four before launching anything.Miss one and the failure looks like a different problemPYTHONPATH…\apps\qgis\pythonPATH…\apps\qgis\bin;…\binQGIS_PREFIX_PATH…\apps\qgisPython can find the modulesthe compiled DLLs loadQGIS finds its own resourcesthe OSGeo4W shell sets all of these before it launches anything

QGIS-version compatibility notes

The bindings are compiled against the exact Python, GDAL, PROJ, and Qt versions bundled with each QGIS release, so version alignment is not optional:

  • QGIS 3.34 LTR / 3.44 LTR: Python 3.12, Qt 5. The examples on this page are pinned here. The launcher name is python-qgis-ltr.bat and the prefix path ends in apps/qgis-ltr.
  • QGIS 4.0+: Qt 6 and a newer Python; the qgis-ltr suffix becomes qgis, so use python-qgis.bat and the apps/qgis prefix.
  • QGIS 3.28 LTR and older: shipped Python 3.9. Methods that appeared in later APIs will raise AttributeError here.

Because method names and enum locations drift between releases, cross-check any snippet against your installed version using the QGIS Python version compatibility guide before assuming it will run. Always drive external scripts with the interpreter that matches the QGIS build whose libraries they import — never a system or conda Python.

Troubleshooting

  • DLL load failed while importing qgis.core — the Visual C++ Redistributable (2015–2022) is missing, or the PATH resolves a conflicting DLL first. Install the latest VC++ runtime and make sure the QGIS bin directories precede any system Python paths. Launching through python-qgis-ltr.bat sidesteps most ordering issues because it sets the environment for you.
  • ModuleNotFoundError: No module named 'qgis' — the interpreter cannot see PYTHONPATH, usually because an IDE points at a plain system Python. Point it at C:\OSGeo4W\bin\python-qgis-ltr.bat, or work through the deeper diagnosis in fixing PyQGIS module import errors.
  • Proxy / network timeouts during install — set http_proxy and https_proxy before launching OSGeo4W, or download the .msi packages manually and choose Install from Local Directory.
  • Third-party packages invisible to PyQGIS — install libraries such as pandas or requests through the bundled shell (python-qgis-ltr.bat -m pip install <package>) so they land in the QGIS interpreter's site-packages and match its ABI. Installing into a system or conda Python leaves them unimportable from PyQGIS.

Conclusion

On Windows, reliable PyQGIS bindings come from installing QGIS itself — through OSGeo4W when you can reach its repository, or the standalone installer with a run_pyqgis.bat launcher when you cannot — and never from pip install pyqgis. Once the headless verification script prints a version and a valid layer, the same interpreter is ready to drive IDEs, scheduled jobs, and standalone tools. From here, move into the interactive QGIS Python Console Basics to explore the API live, then formalize your setup with Virtual Environments for GIS for reproducible builds.

Frequently Asked Questions

Why can't I just run pip install pyqgis to get the bindings on Windows? The PyPI pyqgis package is a documentation stub with no compiled binaries, so it cannot satisfy the C++ dependencies PyQGIS requires. The bindings are tightly coupled to QGIS's bundled GDAL, PROJ, and Qt builds, which must be installed together. Use the OSGeo4W Network Installer or the standalone installer so the binaries and their versions match exactly.

Which Python version do the QGIS Windows bindings require? QGIS 3.34 and later, including 3.44 LTR, bundle Python 3.12, while older releases such as 3.28 LTR shipped Python 3.9. You must use the interpreter that ships with your QGIS install rather than a separately installed Python, because the compiled modules are built against that specific version. Mixing versions produces ImportError or ABI mismatch failures.

How do I install third-party packages like pandas into the QGIS Python environment? Run pip through the bundled shell, for example python-qgis-ltr.bat -m pip install pandas, so packages land in the QGIS interpreter's site-packages. Installing into a system or conda Python instead leaves them invisible to PyQGIS and risks ABI conflicts. Always confirm the install used the OSGeo4W Python before importing the package in a script.

What causes DLL load failed while importing qgis.core on Windows? This usually means the Visual C++ Redistributable (2015–2022) is missing or the system PATH resolves a conflicting DLL before the QGIS one. Install the latest VC++ runtime and ensure the QGIS bin directories appear ahead of any system Python paths. Launching through python-qgis-ltr.bat sidesteps most ordering problems because it sets the environment for you.

Do I need administrator rights to install the bindings? Administrator privileges are needed when the installer registers system-level PATH and PYTHONPATH entries. If you cannot elevate, you can still use the bundled python-qgis-ltr.bat launcher or a per-session batch file that sets the variables for that shell only. This keeps PyQGIS working without modifying machine-wide environment settings.