[{"data":1,"prerenderedAt":542},["ShallowReactive",2],{"doc:\u002Fpyqgis-fundamentals-environment-setup\u002Fdebugging-pyqgis-scripts\u002Ffixing-pyqgis-module-import-errors":3},{"id":4,"title":5,"body":6,"description":535,"extension":536,"meta":537,"navigation":77,"path":538,"seo":539,"stem":540,"__hash__":541},"docs\u002Fpyqgis-fundamentals-environment-setup\u002Fdebugging-pyqgis-scripts\u002Ffixing-pyqgis-module-import-errors\u002Findex.md","Fixing PyQGIS Module Import Errors",{"type":7,"value":8,"toc":530},"minimark",[9,13,30,35,42,352,362,366,424,428,439,448,468,518,526],[10,11,5],"h1",{"id":12},"fixing-pyqgis-module-import-errors",[14,15,16,20,21,24,25,29],"p",{},[17,18,19],"code",{},"ModuleNotFoundError: No module named 'qgis'"," and ",[17,22,23],{},"ImportError: DLL load failed"," occur when your Python interpreter runs outside QGIS’s managed environment. ",[26,27,28],"strong",{},"Fixing PyQGIS module import errors"," requires either injecting QGIS library paths at runtime or executing your script through the QGIS-bundled Python executable.",[31,32,34],"h3",{"id":33},"quick-fix-manual-path-injection","Quick Fix: Manual Path Injection",[14,36,37,38,41],{},"When running scripts externally (VS Code, PyCharm, standalone terminal), inject QGIS paths before any ",[17,39,40],{},"qgis"," imports. Place this block at the top of your script:",[43,44,49],"pre",{"className":45,"code":46,"language":47,"meta":48,"style":48},"language-python shiki shiki-themes github-dark","import sys\nimport os\n\n# Update to match your exact QGIS installation\nQGIS_PREFIX = r\"C:\\Program Files\\QGIS 3.34\" # Windows Standalone\n# QGIS_PREFIX = \"\u002FApplications\u002FQGIS.app\u002FContents\u002FMacOS\" # macOS\n# QGIS_PREFIX = \"\u002Fusr\" # Linux (Debian\u002FUbuntu)\n\n# Inject QGIS Python paths (order matters)\nsys.path.insert(0, os.path.join(QGIS_PREFIX, \"apps\", \"qgis\", \"python\"))\nsys.path.insert(0, os.path.join(QGIS_PREFIX, \"apps\", \"qgis\", \"python\", \"plugins\"))\n\n# Set mandatory environment variables\nos.environ[\"QGIS_PREFIX_PATH\"] = QGIS_PREFIX\nos.environ[\"PATH\"] = os.path.join(QGIS_PREFIX, \"bin\") + os.pathsep + os.environ.get(\"PATH\", \"\")\n\n# Initialize QGIS application context\nfrom qgis.core import QgsApplication\nQgsApplication.setPrefixPath(QGIS_PREFIX, True)\nQgsApplication.initQgis()\nprint(\"PyQGIS environment loaded successfully.\")\n","python","",[17,50,51,64,72,79,86,131,137,143,148,154,187,217,222,228,246,292,297,303,317,332,338],{"__ignoreMap":48},[52,53,56,60],"span",{"class":54,"line":55},"line",1,[52,57,59],{"class":58},"snl16","import",[52,61,63],{"class":62},"s95oV"," sys\n",[52,65,67,69],{"class":54,"line":66},2,[52,68,59],{"class":58},[52,70,71],{"class":62}," os\n",[52,73,75],{"class":54,"line":74},3,[52,76,78],{"emptyLinePlaceholder":77},true,"\n",[52,80,82],{"class":54,"line":81},4,[52,83,85],{"class":84},"sAwPA","# Update to match your exact QGIS installation\n",[52,87,89,93,96,99,103,107,111,114,117,120,123,126,128],{"class":54,"line":88},5,[52,90,92],{"class":91},"sDLfK","QGIS_PREFIX",[52,94,95],{"class":58}," =",[52,97,98],{"class":58}," r",[52,100,102],{"class":101},"sU2Wk","\"",[52,104,106],{"class":105},"sns5M","C:",[52,108,110],{"class":109},"sRjNt","\\P",[52,112,113],{"class":105},"rogram Files",[52,115,116],{"class":109},"\\Q",[52,118,119],{"class":105},"GIS 3",[52,121,122],{"class":91},".",[52,124,125],{"class":105},"34",[52,127,102],{"class":101},[52,129,130],{"class":84}," # Windows Standalone\n",[52,132,134],{"class":54,"line":133},6,[52,135,136],{"class":84},"# QGIS_PREFIX = \"\u002FApplications\u002FQGIS.app\u002FContents\u002FMacOS\" # macOS\n",[52,138,140],{"class":54,"line":139},7,[52,141,142],{"class":84},"# QGIS_PREFIX = \"\u002Fusr\" # Linux (Debian\u002FUbuntu)\n",[52,144,146],{"class":54,"line":145},8,[52,147,78],{"emptyLinePlaceholder":77},[52,149,151],{"class":54,"line":150},9,[52,152,153],{"class":84},"# Inject QGIS Python paths (order matters)\n",[52,155,157,160,163,166,168,171,174,176,179,181,184],{"class":54,"line":156},10,[52,158,159],{"class":62},"sys.path.insert(",[52,161,162],{"class":91},"0",[52,164,165],{"class":62},", os.path.join(",[52,167,92],{"class":91},[52,169,170],{"class":62},", ",[52,172,173],{"class":101},"\"apps\"",[52,175,170],{"class":62},[52,177,178],{"class":101},"\"qgis\"",[52,180,170],{"class":62},[52,182,183],{"class":101},"\"python\"",[52,185,186],{"class":62},"))\n",[52,188,190,192,194,196,198,200,202,204,206,208,210,212,215],{"class":54,"line":189},11,[52,191,159],{"class":62},[52,193,162],{"class":91},[52,195,165],{"class":62},[52,197,92],{"class":91},[52,199,170],{"class":62},[52,201,173],{"class":101},[52,203,170],{"class":62},[52,205,178],{"class":101},[52,207,170],{"class":62},[52,209,183],{"class":101},[52,211,170],{"class":62},[52,213,214],{"class":101},"\"plugins\"",[52,216,186],{"class":62},[52,218,220],{"class":54,"line":219},12,[52,221,78],{"emptyLinePlaceholder":77},[52,223,225],{"class":54,"line":224},13,[52,226,227],{"class":84},"# Set mandatory environment variables\n",[52,229,231,234,237,240,243],{"class":54,"line":230},14,[52,232,233],{"class":62},"os.environ[",[52,235,236],{"class":101},"\"QGIS_PREFIX_PATH\"",[52,238,239],{"class":62},"] ",[52,241,242],{"class":58},"=",[52,244,245],{"class":91}," QGIS_PREFIX\n",[52,247,249,251,254,256,258,261,263,265,268,271,274,277,279,282,284,286,289],{"class":54,"line":248},15,[52,250,233],{"class":62},[52,252,253],{"class":101},"\"PATH\"",[52,255,239],{"class":62},[52,257,242],{"class":58},[52,259,260],{"class":62}," os.path.join(",[52,262,92],{"class":91},[52,264,170],{"class":62},[52,266,267],{"class":101},"\"bin\"",[52,269,270],{"class":62},") ",[52,272,273],{"class":58},"+",[52,275,276],{"class":62}," os.pathsep ",[52,278,273],{"class":58},[52,280,281],{"class":62}," os.environ.get(",[52,283,253],{"class":101},[52,285,170],{"class":62},[52,287,288],{"class":101},"\"\"",[52,290,291],{"class":62},")\n",[52,293,295],{"class":54,"line":294},16,[52,296,78],{"emptyLinePlaceholder":77},[52,298,300],{"class":54,"line":299},17,[52,301,302],{"class":84},"# Initialize QGIS application context\n",[52,304,306,309,312,314],{"class":54,"line":305},18,[52,307,308],{"class":58},"from",[52,310,311],{"class":62}," qgis.core ",[52,313,59],{"class":58},[52,315,316],{"class":62}," QgsApplication\n",[52,318,320,323,325,327,330],{"class":54,"line":319},19,[52,321,322],{"class":62},"QgsApplication.setPrefixPath(",[52,324,92],{"class":91},[52,326,170],{"class":62},[52,328,329],{"class":91},"True",[52,331,291],{"class":62},[52,333,335],{"class":54,"line":334},20,[52,336,337],{"class":62},"QgsApplication.initQgis()\n",[52,339,341,344,347,350],{"class":54,"line":340},21,[52,342,343],{"class":91},"print",[52,345,346],{"class":62},"(",[52,348,349],{"class":101},"\"PyQGIS environment loaded successfully.\"",[52,351,291],{"class":62},[14,353,354],{},[355,356,357,358,361],"em",{},"Note: ",[17,359,360],{},"PYTHONHOME"," is intentionally omitted. Setting it in external environments frequently breaks virtual environments and triggers silent crashes.",[31,363,365],{"id":364},"critical-compatibility-rules","Critical Compatibility Rules",[367,368,369,380,402,412],"ul",{},[370,371,372,375,376,379],"li",{},[26,373,374],{},"Python Version Alignment:"," PyQGIS bindings are compiled against a specific Python ABI. QGIS 3.28 uses Python 3.9, 3.32+ uses 3.10, and 3.34+ uses 3.11. Running an external Python 3.12 interpreter against QGIS 3.28 will immediately fail with ",[17,377,378],{},"ImportError",". Always match your external interpreter to the QGIS release.",[370,381,382,385,386,389,390,393,394,397,398,401],{},[26,383,384],{},"OS Path Variations:"," Windows standalone uses ",[17,387,388],{},"apps\u002Fqgis\u002Fpython",". OSGeo4W requires ",[17,391,392],{},"C:\\OSGeo4W\\apps\\qgis-ltr\\python",". macOS bundles binaries inside ",[17,395,396],{},".app\u002FContents\u002FResources\u002Fpython",". Linux package managers typically handle symlinks automatically, making manual injection unnecessary unless using isolated ",[17,399,400],{},"venv"," environments.",[370,403,404,407,408,411],{},[26,405,406],{},"Architecture Mismatch:"," Modern PyQGIS is strictly 64-bit. Loading it with a 32-bit Python interpreter will fail on ",[17,409,410],{},"QgsApplication"," initialization.",[370,413,414,417,418,423],{},[26,415,416],{},"IDE Isolation:"," PyCharm and VS Code often activate isolated virtual environments that strip inherited system paths. If your IDE configuration feels opaque, reviewing ",[419,420,422],"a",{"href":421},"\u002Fpyqgis-fundamentals-environment-setup\u002F","PyQGIS Fundamentals & Environment Setup"," will help you correctly map interpreter inheritance and site-packages.",[31,425,427],{"id":426},"fallbacks-when-path-injection-fails","Fallbacks When Path Injection Fails",[14,429,430,431,434,435,438],{},"If ",[17,432,433],{},"sys.path"," injection throws ",[17,436,437],{},"ImportError: cannot import name 'QgsApplication'"," or crashes, switch to these proven alternatives:",[440,441,442],"ol",{},[370,443,444,447],{},[26,445,446],{},"Execute via QGIS Python Wrapper","\nBypass external interpreters by calling the bundled executable directly:",[367,449,450,456,462],{},[370,451,452,453],{},"Windows: ",[17,454,455],{},"\"C:\\Program Files\\QGIS 3.34\\bin\\python-qgis.bat\" your_script.py",[370,457,458,459],{},"macOS: ",[17,460,461],{},"\u002FApplications\u002FQGIS.app\u002FContents\u002FMacOS\u002Fbin\u002Fpython3 your_script.py",[370,463,464,465],{},"Linux: ",[17,466,467],{},"qgis --code your_script.py",[440,469,470,487,508],{"start":66},[370,471,472,475,476,479,480,482,483,486],{},[26,473,474],{},"Run Inside the QGIS Python Console","\nOpen QGIS → Plugins → Python Console. Paste your logic or run ",[17,477,478],{},"exec(open('your_script.py').read())",". The console auto-initializes ",[17,481,410],{}," and loads all ",[17,484,485],{},"qgis.*"," namespaces.",[370,488,489,492,493,496,497,500,501,503,504,507],{},[26,490,491],{},"Remove Conflicting PyPI Packages","\nRun ",[17,494,495],{},"pip list | grep qgis"," (macOS\u002FLinux) or ",[17,498,499],{},"pip list | findstr qgis"," (Windows). If you see an unrelated ",[17,502,40],{}," package, uninstall it immediately: ",[17,505,506],{},"pip uninstall qgis",". Official PyQGIS bindings are never distributed via PyPI and will shadow the correct libraries.",[370,509,510,513,514,517],{},[26,511,512],{},"Verify Native Dependency Chains","\nPyQGIS relies on compiled C++ libraries (GDAL, PROJ, Qt). ",[17,515,516],{},"DLL load failed while importing _core"," usually indicates missing Visual C++ Redistributables (Windows) or mismatched GDAL binaries. Repair your QGIS installation or run the OSGeo4W installer in repair mode to restore native dependencies.",[14,519,520,521,525],{},"For persistent runtime crashes or silent failures during plugin execution, structured logging and step-through inspection are essential. Consult ",[419,522,524],{"href":523},"\u002Fpyqgis-fundamentals-environment-setup\u002Fdebugging-pyqgis-scripts\u002F","Debugging PyQGIS Scripts"," to isolate stack traces and validate environment states before deploying to production pipelines.",[527,528,529],"style",{},"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 .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}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 .sns5M, html code.shiki .sns5M{--shiki-default:#DBEDFF}html pre.shiki code .sRjNt, html code.shiki .sRjNt{--shiki-default:#85E89D;--shiki-default-font-weight:bold}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);}",{"title":48,"searchDepth":66,"depth":66,"links":531},[532,533,534],{"id":33,"depth":74,"text":34},{"id":364,"depth":74,"text":365},{"id":426,"depth":74,"text":427},"ModuleNotFoundError: No module named 'qgis' and ImportError: DLL load failed occur when your Python interpreter runs outside QGIS’s managed environment. Fixing PyQGIS module import errors requires either injecting QGIS library paths at runtime or executing your script through the QGIS-bundled Python executable.","md",{},"\u002Fpyqgis-fundamentals-environment-setup\u002Fdebugging-pyqgis-scripts\u002Ffixing-pyqgis-module-import-errors",{"title":5,"description":535},"pyqgis-fundamentals-environment-setup\u002Fdebugging-pyqgis-scripts\u002Ffixing-pyqgis-module-import-errors\u002Findex","Sf-GKF9_SMvnDMu3y-J7gTY5x1y0egeGV5mwniKmDqw",1777824788948]