How to Install QGIS Python Bindings on Windows

The fastest and officially supported method to install QGIS Python bindings on Windows is through the OSGeo4W Network Installer. It automatically resolves compiled C++ dependencies, configures required environment variables, 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 and lacks the Windows binaries required for PyQGIS.

Compatibility Checklist

  • OS: Windows 10/11 64-bit only (32-bit deprecated in QGIS 3.20)
  • QGIS Version: 3.28 LTR or 3.34+ current
  • Python Version: 3.10 (QGIS 3.28–3.30) or 3.12 (QGIS 3.34+)
  • Architecture: Strictly 64-bit. Mixing 32-bit Python with 64-bit QGIS DLLs triggers ImportError
  • Permissions: Administrator rights required for system PATH and PYTHONPATH registration
  • Environment Conflicts: Standalone Anaconda/Miniconda base environments frequently shadow QGIS paths. Use isolated environments or the bundled OSGeo4W Python.
  1. Download the OSGeo4W Network Installer (64-bit) from the official QGIS download page.
  2. Run the installer, select Install from Internet, and accept the default root (C:\OSGeo4W). Avoid spaces or special characters in the install path.
  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 like gdal-python and numpy auto-select.
  5. Complete installation. The installer automatically registers QGIS_PREFIX_PATH, PYTHONPATH, and appends QGIS bin directories to your system PATH.

Verify the Bindings

Launch the QGIS-managed Python shell to bypass system Python interference:

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

Run this verification script:

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()

Successful execution confirms correct module resolution. For interactive workflows, see QGIS Python Console Basics to learn how the console handles auto-completion, project context, and layer management.

Method 2: Standalone Installer (Manual Config)

If corporate firewalls block OSGeo4W downloads, use the official QGIS Windows Standalone Installer. This method requires manual environment configuration since it does not auto-register Python paths.

  1. Install the standalone package (default: C:\Program Files\QGIS 3.34).
  2. Create a session launcher (run_pyqgis.bat):
@echo off
set "QGIS_ROOT=C:\Program Files\QGIS 3.34"
set "PATH=%QGIS_ROOT%\bin;%QGIS_ROOT%\apps\qgis\bin;%PATH%"
set "PYTHONPATH=%QGIS_ROOT%\apps\qgis\python;%QGIS_ROOT%\apps\qgis\python\qgis;%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 accessible only for that session. Adjust Python312 to match your bundled Python version if needed.

Troubleshooting & IDE Integration

  • DLL load failed while importing qgis.core: Missing Visual C++ Redistributable (2015–2022) or PATH ordering conflict. Install the latest VC++ runtime and ensure QGIS bin directories appear before system Python paths.
  • ModuleNotFoundError: No module named 'qgis': Your IDE is pointing to a system Python interpreter. Configure your IDE to use C:\OSGeo4W\bin\python-qgis-ltr.bat or create a virtual environment that inherits OSGeo4W paths.
  • Proxy/Network Timeouts: Set http_proxy and https_proxy environment variables before launching OSGeo4W, or download .msi packages manually and select Install from Local Directory.
  • External Package Compatibility: Third-party libraries (pandas, requests, etc.) must be installed via the bundled shell: python-qgis-ltr.bat -m pip install <package>. This prevents ABI mismatches with QGIS's compiled Python.

For comprehensive dependency management, virtual environment strategies, and project structure guidelines, review PyQGIS Fundamentals & Environment Setup.