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 since QGIS 3.20)
  • QGIS Version: 3.44 LTR or 4.0+ current
  • Python Version: 3.12 (QGIS 3.34 and later, including 3.44 LTR); older releases like 3.28 LTR bundled 3.9
  • 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.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 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 as the interpreter, or create a virtual environment that inherits OSGeo4W paths via a .pth file.
  • 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.

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.