[{"data":1,"prerenderedAt":564},["ShallowReactive",2],{"doc:\u002Fpyqgis-fundamentals-environment-setup\u002Fqgis-python-console-basics\u002Fhow-to-install-qgis-python-bindings-on-windows":3},{"id":4,"title":5,"body":6,"description":557,"extension":558,"meta":559,"navigation":236,"path":560,"seo":561,"stem":562,"__hash__":563},"docs\u002Fpyqgis-fundamentals-environment-setup\u002Fqgis-python-console-basics\u002Fhow-to-install-qgis-python-bindings-on-windows\u002Findex.md","How to Install QGIS Python Bindings on Windows",{"type":7,"value":8,"toc":550},"minimark",[9,13,38,43,93,97,174,178,181,197,200,387,396,400,403,419,461,470,474,539,546],[10,11,5],"h1",{"id":12},"how-to-install-qgis-python-bindings-on-windows",[14,15,16,17,21,22,26,27,30,31,37],"p",{},"The fastest and officially supported method to install QGIS Python bindings on Windows is through the ",[18,19,20],"strong",{},"OSGeo4W Network Installer",". It automatically resolves compiled C++ dependencies, configures required environment variables, and links ",[23,24,25],"code",{},"qgis.core"," and ",[23,28,29],{},"qgis.gui"," to a managed Python runtime. ",[18,32,33,34],{},"Do not run ",[23,35,36],{},"pip install pyqgis","—the PyPI package is a documentation stub and lacks the Windows binaries required for PyQGIS.",[39,40,42],"h3",{"id":41},"compatibility-checklist","Compatibility Checklist",[44,45,46,53,59,65,74,87],"ul",{},[47,48,49,52],"li",{},[18,50,51],{},"OS:"," Windows 10\u002F11 64-bit only (32-bit deprecated in QGIS 3.20)",[47,54,55,58],{},[18,56,57],{},"QGIS Version:"," 3.28 LTR or 3.34+ current",[47,60,61,64],{},[18,62,63],{},"Python Version:"," 3.10 (QGIS 3.28–3.30) or 3.12 (QGIS 3.34+)",[47,66,67,70,71],{},[18,68,69],{},"Architecture:"," Strictly 64-bit. Mixing 32-bit Python with 64-bit QGIS DLLs triggers ",[23,72,73],{},"ImportError",[47,75,76,79,80,26,83,86],{},[18,77,78],{},"Permissions:"," Administrator rights required for system ",[23,81,82],{},"PATH",[23,84,85],{},"PYTHONPATH"," registration",[47,88,89,92],{},[18,90,91],{},"Environment Conflicts:"," Standalone Anaconda\u002FMiniconda base environments frequently shadow QGIS paths. Use isolated environments or the bundled OSGeo4W Python.",[39,94,96],{"id":95},"method-1-osgeo4w-network-installer-recommended","Method 1: OSGeo4W Network Installer (Recommended)",[98,99,100,107,118,133,158],"ol",{},[47,101,102,103,106],{},"Download the ",[18,104,105],{},"OSGeo4W Network Installer (64-bit)"," from the official QGIS download page.",[47,108,109,110,113,114,117],{},"Run the installer, select ",[23,111,112],{},"Install from Internet",", and accept the default root (",[23,115,116],{},"C:\\OSGeo4W","). Avoid spaces or special characters in the install path.",[47,119,120,121,124,125,128,129,132],{},"In the package selection screen, expand ",[23,122,123],{},"Desktop"," and check ",[23,126,127],{},"qgis-ltr"," (recommended) or ",[23,130,131],{},"qgis",".",[47,134,135,136,139,140,143,144,26,147,150,151,26,154,157],{},"Expand ",[23,137,138],{},"Libs"," → ",[23,141,142],{},"Python"," and verify ",[23,145,146],{},"python3-qgis",[23,148,149],{},"python3-qgis-common"," are selected. Dependencies like ",[23,152,153],{},"gdal-python",[23,155,156],{},"numpy"," auto-select.",[47,159,160,161,164,165,167,168,171,172,132],{},"Complete installation. The installer automatically registers ",[23,162,163],{},"QGIS_PREFIX_PATH",", ",[23,166,85],{},", and appends QGIS ",[23,169,170],{},"bin"," directories to your system ",[23,173,82],{},[39,175,177],{"id":176},"verify-the-bindings","Verify the Bindings",[14,179,180],{},"Launch the QGIS-managed Python shell to bypass system Python interference:",[182,183,188],"pre",{"className":184,"code":185,"language":186,"meta":187,"style":187},"language-cmd shiki shiki-themes github-dark","C:\\OSGeo4W\\bin\\python-qgis-ltr.bat\n","cmd","",[23,189,190],{"__ignoreMap":187},[191,192,195],"span",{"class":193,"line":194},"line",1,[191,196,185],{},[14,198,199],{},"Run this verification script:",[182,201,205],{"className":202,"code":203,"language":204,"meta":187,"style":187},"language-python shiki shiki-themes github-dark","import qgis.core\nfrom qgis.core import QgsApplication\n\nprint(f\"PyQGIS loaded: {qgis.core.Qgis.QGIS_VERSION}\")\n\n# Match your installation type: qgis-ltr or qgis\nQgsApplication.setPrefixPath(\"C:\u002FOSGeo4W\u002Fapps\u002Fqgis-ltr\", True)\nqgs = QgsApplication([], False)\nqgs.initQgis()\n\nlayer = qgis.core.QgsVectorLayer(\"Point\", \"temp\", \"memory\")\nprint(f\"Test layer valid: {layer.isValid()}\")\n\nqgs.exitQgis()\n","python",[23,206,207,217,231,238,270,275,282,298,315,321,326,352,376,381],{"__ignoreMap":187},[191,208,209,213],{"class":193,"line":194},[191,210,212],{"class":211},"snl16","import",[191,214,216],{"class":215},"s95oV"," qgis.core\n",[191,218,220,223,226,228],{"class":193,"line":219},2,[191,221,222],{"class":211},"from",[191,224,225],{"class":215}," qgis.core ",[191,227,212],{"class":211},[191,229,230],{"class":215}," QgsApplication\n",[191,232,234],{"class":193,"line":233},3,[191,235,237],{"emptyLinePlaceholder":236},true,"\n",[191,239,241,245,248,251,255,258,261,264,267],{"class":193,"line":240},4,[191,242,244],{"class":243},"sDLfK","print",[191,246,247],{"class":215},"(",[191,249,250],{"class":211},"f",[191,252,254],{"class":253},"sU2Wk","\"PyQGIS loaded: ",[191,256,257],{"class":243},"{",[191,259,260],{"class":215},"qgis.core.Qgis.",[191,262,263],{"class":243},"QGIS_VERSION}",[191,265,266],{"class":253},"\"",[191,268,269],{"class":215},")\n",[191,271,273],{"class":193,"line":272},5,[191,274,237],{"emptyLinePlaceholder":236},[191,276,278],{"class":193,"line":277},6,[191,279,281],{"class":280},"sAwPA","# Match your installation type: qgis-ltr or qgis\n",[191,283,285,288,291,293,296],{"class":193,"line":284},7,[191,286,287],{"class":215},"QgsApplication.setPrefixPath(",[191,289,290],{"class":253},"\"C:\u002FOSGeo4W\u002Fapps\u002Fqgis-ltr\"",[191,292,164],{"class":215},[191,294,295],{"class":243},"True",[191,297,269],{"class":215},[191,299,301,304,307,310,313],{"class":193,"line":300},8,[191,302,303],{"class":215},"qgs ",[191,305,306],{"class":211},"=",[191,308,309],{"class":215}," QgsApplication([], ",[191,311,312],{"class":243},"False",[191,314,269],{"class":215},[191,316,318],{"class":193,"line":317},9,[191,319,320],{"class":215},"qgs.initQgis()\n",[191,322,324],{"class":193,"line":323},10,[191,325,237],{"emptyLinePlaceholder":236},[191,327,329,332,334,337,340,342,345,347,350],{"class":193,"line":328},11,[191,330,331],{"class":215},"layer ",[191,333,306],{"class":211},[191,335,336],{"class":215}," qgis.core.QgsVectorLayer(",[191,338,339],{"class":253},"\"Point\"",[191,341,164],{"class":215},[191,343,344],{"class":253},"\"temp\"",[191,346,164],{"class":215},[191,348,349],{"class":253},"\"memory\"",[191,351,269],{"class":215},[191,353,355,357,359,361,364,366,369,372,374],{"class":193,"line":354},12,[191,356,244],{"class":243},[191,358,247],{"class":215},[191,360,250],{"class":211},[191,362,363],{"class":253},"\"Test layer valid: ",[191,365,257],{"class":243},[191,367,368],{"class":215},"layer.isValid()",[191,370,371],{"class":243},"}",[191,373,266],{"class":253},[191,375,269],{"class":215},[191,377,379],{"class":193,"line":378},13,[191,380,237],{"emptyLinePlaceholder":236},[191,382,384],{"class":193,"line":383},14,[191,385,386],{"class":215},"qgs.exitQgis()\n",[14,388,389,390,395],{},"Successful execution confirms correct module resolution. For interactive workflows, see ",[391,392,394],"a",{"href":393},"\u002Fpyqgis-fundamentals-environment-setup\u002Fqgis-python-console-basics\u002F","QGIS Python Console Basics"," to learn how the console handles auto-completion, project context, and layer management.",[39,397,399],{"id":398},"method-2-standalone-installer-manual-config","Method 2: Standalone Installer (Manual Config)",[14,401,402],{},"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.",[98,404,405,412],{},[47,406,407,408,411],{},"Install the standalone package (default: ",[23,409,410],{},"C:\\Program Files\\QGIS 3.34",").",[47,413,414,415,418],{},"Create a session launcher (",[23,416,417],{},"run_pyqgis.bat","):",[182,420,424],{"className":421,"code":422,"language":423,"meta":187,"style":187},"language-bat shiki shiki-themes github-dark","@echo off\nset \"QGIS_ROOT=C:\\Program Files\\QGIS 3.34\"\nset \"PATH=%QGIS_ROOT%\\bin;%QGIS_ROOT%\\apps\\qgis\\bin;%PATH%\"\nset \"PYTHONPATH=%QGIS_ROOT%\\apps\\qgis\\python;%QGIS_ROOT%\\apps\\qgis\\python\\qgis;%PYTHONPATH%\"\nset \"QGIS_PREFIX_PATH=%QGIS_ROOT%\\apps\\qgis\"\nset \"PYTHONHOME=%QGIS_ROOT%\\apps\\Python312\"\n\"%QGIS_ROOT%\\bin\\python3.exe\"\n","bat",[23,425,426,431,436,441,446,451,456],{"__ignoreMap":187},[191,427,428],{"class":193,"line":194},[191,429,430],{},"@echo off\n",[191,432,433],{"class":193,"line":219},[191,434,435],{},"set \"QGIS_ROOT=C:\\Program Files\\QGIS 3.34\"\n",[191,437,438],{"class":193,"line":233},[191,439,440],{},"set \"PATH=%QGIS_ROOT%\\bin;%QGIS_ROOT%\\apps\\qgis\\bin;%PATH%\"\n",[191,442,443],{"class":193,"line":240},[191,444,445],{},"set \"PYTHONPATH=%QGIS_ROOT%\\apps\\qgis\\python;%QGIS_ROOT%\\apps\\qgis\\python\\qgis;%PYTHONPATH%\"\n",[191,447,448],{"class":193,"line":272},[191,449,450],{},"set \"QGIS_PREFIX_PATH=%QGIS_ROOT%\\apps\\qgis\"\n",[191,452,453],{"class":193,"line":277},[191,454,455],{},"set \"PYTHONHOME=%QGIS_ROOT%\\apps\\Python312\"\n",[191,457,458],{"class":193,"line":284},[191,459,460],{},"\"%QGIS_ROOT%\\bin\\python3.exe\"\n",[98,462,463],{"start":233},[47,464,465,466,469],{},"Double-click the batch file. It opens a terminal with PyQGIS accessible only for that session. Adjust ",[23,467,468],{},"Python312"," to match your bundled Python version if needed.",[39,471,473],{"id":472},"troubleshooting-ide-integration","Troubleshooting & IDE Integration",[44,475,476,490,502,522],{},[47,477,478,483,484,486,487,489],{},[18,479,480],{},[23,481,482],{},"DLL load failed while importing qgis.core",": Missing Visual C++ Redistributable (2015–2022) or ",[23,485,82],{}," ordering conflict. Install the latest VC++ runtime and ensure QGIS ",[23,488,170],{}," directories appear before system Python paths.",[47,491,492,497,498,501],{},[18,493,494],{},[23,495,496],{},"ModuleNotFoundError: No module named 'qgis'",": Your IDE is pointing to a system Python interpreter. Configure your IDE to use ",[23,499,500],{},"C:\\OSGeo4W\\bin\\python-qgis-ltr.bat"," or create a virtual environment that inherits OSGeo4W paths.",[47,503,504,507,508,26,511,514,515,518,519,132],{},[18,505,506],{},"Proxy\u002FNetwork Timeouts",": Set ",[23,509,510],{},"http_proxy",[23,512,513],{},"https_proxy"," environment variables before launching OSGeo4W, or download ",[23,516,517],{},".msi"," packages manually and select ",[23,520,521],{},"Install from Local Directory",[47,523,524,527,528,164,531,534,535,538],{},[18,525,526],{},"External Package Compatibility",": Third-party libraries (",[23,529,530],{},"pandas",[23,532,533],{},"requests",", etc.) must be installed via the bundled shell: ",[23,536,537],{},"python-qgis-ltr.bat -m pip install \u003Cpackage>",". This prevents ABI mismatches with QGIS's compiled Python.",[14,540,541,542,132],{},"For comprehensive dependency management, virtual environment strategies, and project structure guidelines, review ",[391,543,545],{"href":544},"\u002Fpyqgis-fundamentals-environment-setup\u002F","PyQGIS Fundamentals & Environment Setup",[547,548,549],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .snl16, html code.shiki .snl16{--shiki-default:#F97583}html pre.shiki code .s95oV, html code.shiki .s95oV{--shiki-default:#E1E4E8}html pre.shiki code .sDLfK, html code.shiki .sDLfK{--shiki-default:#79B8FF}html pre.shiki code .sU2Wk, html code.shiki .sU2Wk{--shiki-default:#9ECBFF}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}",{"title":187,"searchDepth":219,"depth":219,"links":551},[552,553,554,555,556],{"id":41,"depth":233,"text":42},{"id":95,"depth":233,"text":96},{"id":176,"depth":233,"text":177},{"id":398,"depth":233,"text":399},{"id":472,"depth":233,"text":473},"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.","md",{},"\u002Fpyqgis-fundamentals-environment-setup\u002Fqgis-python-console-basics\u002Fhow-to-install-qgis-python-bindings-on-windows",{"title":5,"description":557},"pyqgis-fundamentals-environment-setup\u002Fqgis-python-console-basics\u002Fhow-to-install-qgis-python-bindings-on-windows\u002Findex","WzVVXYkFjKQOccNLeeNocJmr6IjU6holhkMEPUz0bLw",1777824788925]