Virtual Environments for GIS: A Step-by-Step Guide for QGIS and PyQGIS

Geospatial development relies heavily on complex, interdependent libraries. GDAL, PROJ, NumPy, and the QGIS Python bindings must align precisely to avoid silent failures or corrupted spatial operations. Isolating project dependencies with a Python virtual environment has become a standard practice for modern spatial analysts and developers. By separating a project's packages from your system-wide Python installation, you gain reproducible builds, cleaner dependency trees, and the ability to test PyQGIS scripts without risking your core QGIS installation.

This guide builds on the PyQGIS Fundamentals & Environment Setup overview and focuses on one job: standing up an isolated Python environment that can import qgis.core correctly. It is a companion to configuring the QGIS Python Console for in-app work and to Setting Up PyCharm for QGIS for IDE-driven development — a virtual environment is the artifact all of those workflows attach to. Whether you are automating map exports, building custom processing algorithms, or integrating spatial data pipelines, a properly configured environment ensures your code behaves consistently across deployments.

Virtual environment layering over QGIS bundled PythonQGIS ships its own Python interpreter with compiled qgis bindings and GDAL or PROJ. A venv created with the system flag inherits those bindings, then layers pure-Python pip packages on top.QGIS-Bundled Python(the interpreter QGIS installs)python3.12 (matches QGIS 3.34 LTR)qgis.core / qgis.gui bindingscompiled GDAL / PROJ / Qtversion-locked C extensionsYour venv--system-site-packagesinherits qgis bindings + GDALfrom the bundled Python (no copy)pip install requests, pandas, ...pure-Python deps layered on topnever pip install gdal here

Prerequisites

Before configuring an isolated workspace, ensure your system meets the following baseline requirements:

  1. QGIS Installed: A stable Long-Term Release (LTR) or current stable version must be installed on your machine. The virtual environment will reference QGIS's bundled Python interpreter and compiled C-extensions.
  2. Terminal/Command Line Access: You will need to execute shell commands. Windows users should use Command Prompt or PowerShell; macOS/Linux users should use Terminal.
  3. Basic Python Familiarity: Understanding how Python resolves modules, how sys.path works, and how to activate/deactivate environments will streamline the process. If you are new to executing code within QGIS itself, reviewing QGIS Python Console Basics will provide essential context before moving to external environments.
  4. Write Permissions: Ensure you have write access to the directory where you plan to create the virtual environment.

Step-by-Step Workflow

The following workflow creates a self-contained Python environment that mirrors your QGIS installation's Python version and library paths.

Step 1: Locate the QGIS Python Executable

QGIS ships with its own Python distribution to guarantee compatibility with compiled spatial libraries. You must identify the exact path to this interpreter.

  • Windows: Typically C:\OSGeo4W\apps\Python312\python.exe (QGIS 3.34+, including 3.44 LTR) or C:\OSGeo4W\apps\Python39\python.exe (older QGIS 3.28)
  • macOS: Usually /Applications/QGIS.app/Contents/MacOS/bin/python3
  • Linux: Often /usr/bin/python3 (package manager) or /opt/qgis/bin/python3

Open your terminal and verify the version:

"<path-to-qgis-python>" --version

The output should match your QGIS version's Python release (e.g., Python 3.9.x or 3.12.x).

Step 2: Create the Virtual Environment

Use Python's built-in venv module to generate the isolated directory. Replace <path-to-qgis-python> with the executable located in Step 1, and gis_env with your preferred environment name.

"<path-to-qgis-python>" -m venv gis_env

This command creates a gis_env folder containing a private Python binary, pip, and an empty site-packages directory.

Step 3: Activate the Environment

Activation modifies your shell's PATH variable so that python and pip commands point to the virtual environment.

  • Windows (CMD): gis_env\Scripts\activate.bat
  • Windows (PowerShell): gis_env\Scripts\Activate.ps1
  • macOS/Linux: source gis_env/bin/activate

Your terminal prompt should now display (gis_env).

Step 4: Map QGIS Paths & Environment Variables

The virtual environment does not automatically know where QGIS's compiled modules reside. You must explicitly point it to the QGIS python and site-packages directories, then set the required environment variables.

1. Create a .pth file Navigate to your environment's site-packages folder and create a file named qgis.pth. Add the absolute paths to QGIS's Python libraries (one per line). Do not use relative paths.

  • Windows example paths (QGIS 3.44 LTR via OSGeo4W): 
    C:\OSGeo4W\apps\qgis-ltr\python
C:\OSGeo4W\apps\Python312\Lib\site-packages
  • macOS example paths: 
    /Applications/QGIS.app/Contents/Resources/python
/Applications/QGIS.app/Contents/Resources/python/plugins

2. Update the activation script Open your environment's activation script (Scripts/activate.bat for Windows CMD, Scripts/Activate.ps1 for PowerShell, or bin/activate for macOS/Linux) and append the following variables. This ensures they load automatically every time you activate the environment.

macOS/Linux (bin/activate):

export QGIS_PREFIX_PATH="/Applications/QGIS.app/Contents/MacOS"
export PYTHONPATH="${QGIS_PREFIX_PATH}/../Resources/python:${QGIS_PREFIX_PATH}/../Resources/python/plugins:${PYTHONPATH}"
export PATH="${QGIS_PREFIX_PATH}/bin:${PATH}"

Windows CMD (Scripts/activate.bat):

set "QGIS_PREFIX_PATH=C:\OSGeo4W\apps\qgis-ltr"
set "PATH=%QGIS_PREFIX_PATH%\bin;C:\OSGeo4W\bin;%PATH%"

Windows PowerShell (Scripts/Activate.ps1):

$env:QGIS_PREFIX_PATH = "C:\OSGeo4W\apps\qgis-ltr"
$env:PATH = "$env:QGIS_PREFIX_PATH\bin;C:\OSGeo4W\bin;$env:PATH"

Once configured, your environment is ready. Developers who prefer integrated development environments should review Setting Up PyCharm for QGIS to attach this exact environment to a professional IDE for debugging, linting, and autocomplete.

Code Breakdown & Execution

After activation, verify that PyQGIS imports correctly. Create a file named verify_qgis.py with the following content:

import sys
import os

def check_pyqgis():
    try:
        from qgis.core import QgsApplication
        from osgeo import gdal, ogr

        print(f"Python Executable: {sys.executable}")
        print(f"Python Version: {sys.version}")
        print(f"GDAL Version: {gdal.__version__}")

        # Initialize QGIS application (required for headless operations)
        prefix = os.environ.get("QGIS_PREFIX_PATH", "")
        qgs = QgsApplication([], False)
        qgs.setPrefixPath(prefix, True)
        qgs.initQgis()

        print("QGIS Core Import: SUCCESS")
        print("QGIS Application Initialized: SUCCESS")

        qgs.exitQgis()
        return True
    except ImportError as e:
        print(f"Import Error: {e}")
        return False
    except Exception as e:
        print(f"Initialization Error: {e}")
        return False

if __name__ == "__main__":
    check_pyqgis()

How It Works

  1. Module Resolution: The script imports qgis.core and osgeo. If the .pth paths are correct, Python resolves these without raising ModuleNotFoundError.
  2. Prefix Path Configuration: QgsApplication.setPrefixPath() tells the QGIS API where to find plugins, SVG resources, and CRS databases. This is mandatory when running PyQGIS outside the desktop GUI.
  3. Headless Initialization: qgs.initQgis() bootstraps the C++ backend. Without this, spatial operations like QgsVectorLayer will fail silently or crash.
  4. Graceful Exit: qgs.exitQgis() releases memory and cleans up GDAL drivers, preventing file locks on Windows.

Executing this script demonstrates how to reliably run Running Python scripts outside QGIS desktop, which is essential for automated ETL pipelines, scheduled geoprocessing tasks, and CI/CD workflows.

Common Errors & Resolutions

Even with careful setup, environment mismatches occur. Below are the most frequent issues and their tested resolutions. If you would rather step through failures interactively, pair this section with Debugging PyQGIS Scripts, which covers reading tracebacks and inspecting sys.path at runtime.

Routing a failed import qgis.core to the right fixStarting from a failing import qgis.core, four symptoms branch to their fixes: ModuleNotFoundError means fix the qgis.pth paths; WinError 126 means add the QGIS bin folder to PATH; a segfault on Apple Silicon means use the bundled Python with arch -arm64 pip; and a CRS or srs.db error means set QGIS_PREFIX_PATH before setPrefixPath.import qgis.core failsModuleNotFoundError'qgis.core' missingWinError 126DLL not foundSegfault on importApple Silicon ARM64CRS / srs.db errorapp init failsFix qgis.pthabsolute paths toQGIS python folderAdd QGIS binto PATH, prependbefore import qgisBundled Python +arch -arm64 pipinstall packagesSet prefix pathQGIS_PREFIX_PATHbefore setPrefixPath

1. ModuleNotFoundError: No module named 'qgis.core'

Cause: The .pth file is missing, points to the wrong directory, or contains syntax errors. Fix:

  • Verify the exact path to QGIS's Python libraries using find /usr -name "qgis" -type d 2>/dev/null (Unix) or dir /s /b qgis 2>nul (Windows) in the QGIS install tree.
  • Ensure the .pth file contains absolute paths, not relative ones.
  • Re-run python -c "import sys; print(sys.path)" to confirm the QGIS paths appear in the list.

2. OSError: [WinError 126] The specified module could not be found

Cause: Windows cannot locate GDAL or Qt DLLs because PATH does not include the QGIS bin directory. Fix:

  • Add the QGIS bin folder to your system PATH before importing qgis.
  • In your activation script, prepend the path exactly as shown in Step 4.
  • Restart the terminal after modifying environment variables.

3. Architecture Mismatch on Apple Silicon

Cause: QGIS on macOS Silicon runs natively as ARM64, but some third-party Python wheels are compiled for x86_64. Mixing architectures causes segmentation faults during import. Fix:

  • Always use the QGIS-bundled Python interpreter to create the venv. Do not use Homebrew or system Python.
  • If installing additional packages, force architecture compatibility: arch -arm64 pip install <package>

4. QgsApplication fails to find CRS database

Cause: Missing QGIS_PREFIX_PATH or incorrect value pointing to the wrong directory. Fix:

  • Print os.environ.get("QGIS_PREFIX_PATH") to verify it points to the QGIS prefix (e.g., /Applications/QGIS.app/Contents/MacOS or C:\OSGeo4W\apps\qgis-ltr).
  • On Linux, ensure the user has read access to /usr/share/qgis or /opt/qgis/share/qgis.
  • Check that the resources/srs.db file exists under the QGIS share directory.

5. GDAL/PROJ Version Conflicts

Cause: Installing gdal via pip in the virtual environment overwrites the QGIS-bundled version, breaking spatial transformations. Fix:

  • Never run pip install gdal inside a PyQGIS virtual environment. QGIS already provides a compiled, version-locked GDAL.
  • If you need additional geospatial packages, use pip install --no-deps <package> to prevent dependency resolution from pulling incompatible C-extensions.

Best Practices for Production Deployment

Once your environment is stable, adopt these practices to maintain reliability across projects:

  • Freeze Dependencies: Run pip freeze > requirements.txt only for packages you explicitly installed. Do not include QGIS core modules in your requirements file.
  • Use venv Over conda for PyQGIS: While Conda is excellent for data science, QGIS's Python distribution is tightly coupled with its C++ binaries. venv preserves this linkage without introducing Conda's environment resolution overhead.
  • Isolate Per Project: Never share a single virtual environment across multiple GIS projects. Different projects often require different plugin versions or CRS databases.
  • Document Path Overrides: Keep a setup.sh or setup.bat in your repository that exports the correct QGIS_PREFIX_PATH and PYTHONPATH. This ensures new developers or CI runners can bootstrap the environment with a single command.

Why a plain virtualenv is not enough

The usual Python answer to dependency isolation — create a virtual environment, install what you need — breaks down for PyQGIS because the QGIS bindings are compiled C++ extensions that cannot be installed with pip. They exist only inside the QGIS installation, built against one specific Python version.

Three ways to isolate dependencies around QGISA plain virtual environment built from a downloaded Python cannot import the QGIS bindings at all. A virtual environment created from the QGIS-bundled interpreter with system site packages enabled can import them while still isolating your own dependencies. A container image bundles a specific QGIS version with the environment, which is the only fully reproducible option.pip cannot install the QGIS bindings — plan around thata plain virtualenvpython -m venv .venv✗isolates your packagescannot import qgis at allthe default answer, and wrongvenv + system packages--system-site-packages✓isolates your packagessees the QGIS bindingsbuilt from the bundled pythona container imageFROM qgis/qgis:3.34✓pins QGIS itselffully reproduciblethe answer for CI and servers

The middle option is the pragmatic one for local work. Creating the environment from the QGIS-bundled interpreter keeps the ABI matched, and --system-site-packages lets it see the compiled bindings while your own pip installs still land inside the environment rather than polluting the QGIS installation.

That last point matters more than it sounds. Installing packages directly into the QGIS Python is tempting and creates a machine nobody else can reproduce — and on a system-package install of QGIS it will be silently reverted by the next update. Keeping your dependencies in an environment you own means the QGIS installation stays exactly as the packager built it.

For anything that runs unattended, the container is the honest answer. It pins not just your Python dependencies but the QGIS version, the GDAL version and the PROJ transformation grids, all of which affect results. A pipeline that produces slightly different coordinates after a server update is a genuinely difficult problem to diagnose, and pinning the whole stack is the only thing that prevents it.

Key Takeaways

  • Build the environment on the QGIS-bundled interpreter, or create it with --system-site-packages, so it can see the compiled qgis.core and qgis.gui bindings. A venv from a different Python minor version will fail to import them.
  • Map QGIS paths explicitly with a qgis.pth file of absolute paths plus QGIS_PREFIX_PATH and PATH exports in your activation script. Without them, imports fail or the CRS database (srs.db) cannot be found.
  • Never pip install gdal or pip install pyproj into a PyQGIS environment — QGIS ships version-locked, compiled builds, and shadowing them breaks spatial transformations. Reserve pip for pure-Python packages, using --no-deps when a package might pull conflicting C extensions.
  • Always call setPrefixPath() before initQgis() and pair initQgis() with exitQgis() for clean headless runs — this is what lets you run Python scripts outside QGIS Desktop in ETL and CI pipelines.
  • Isolate one environment per project and commit a setup.sh/setup.bat that exports the paths, so teammates and CI runners reproduce it in one command.

Together these habits turn PyQGIS development from a fragile, system-dependent process into a reproducible workflow that scales from a single script to enterprise geoprocessing pipelines, and stays robust across operating systems, QGIS updates, and team collaborations.

Frequently Asked Questions

Why can't I just pip install qgis into a regular virtual environment? The qgis package on PyPI is a documentation stub, not the actual bindings. The real qgis.core and qgis.gui modules are compiled C++ extensions shipped only with the QGIS installer. You must reference QGIS's bundled Python paths via a .pth file or --system-site-packages, rather than installing them from PyPI.

Should I create the venv with the QGIS Python or with my system Python? Always base it on the QGIS-bundled interpreter (or use --system-site-packages so the venv can see QGIS's compiled bindings). The PyQGIS bindings are compiled against a specific Python ABI, so a venv built from a different minor version (for example system Python 3.11 against QGIS 3.34's Python 3.12) will fail to import qgis.core.

Is it safe to pip install gdal or pip install pyproj inside the environment? No. QGIS already ships compiled, version-locked GDAL and PROJ. Installing them from pip overwrites or shadows those binaries and breaks spatial transformations. Limit pip installs to pure-Python packages, and use pip install --no-deps <package> when a dependency might pull in conflicting C extensions.

Why does my script raise a CRS database error even though imports succeed? This almost always means QGIS_PREFIX_PATH is unset or points to the wrong directory, so QGIS cannot find srs.db. Verify it points to the QGIS prefix (for example C:\OSGeo4W\apps\qgis-ltr or /Applications/QGIS.app/Contents/MacOS) and that setPrefixPath() is called before initQgis().

Should I use venv or Conda for PyQGIS work? For replicating an existing desktop QGIS install, venv is preferred because it preserves the tight coupling between QGIS's Python and its C++ binaries. Conda is a reasonable fallback when you need a fully self-contained install (for example on a headless CI runner) via conda install -c conda-forge qgis, but mixing a Conda QGIS with a desktop QGIS on the same machine invites path conflicts.

Can I pip install PyQGIS into a virtual environment? No. The bindings are compiled against a specific Python and ship only inside QGIS, so there is no installable package. Create the environment from the QGIS-bundled interpreter with system site packages enabled, which lets it see the bindings while keeping your own dependencies separate.

Is it safe to install packages into the QGIS Python directly? It works and it is a poor idea. On a system-package installation the changes are reverted by the next QGIS update, and on any installation it produces a machine nobody else can reproduce. Keep your dependencies in an environment you control.

How do I make results reproducible across machines? Pin the whole stack, not just the Python packages. QGIS, GDAL and the PROJ transformation grids all affect numeric output, which is why a container image built from a tagged QGIS release is the only fully reproducible option for scheduled work.

Which Python should the environment be created from? The one QGIS itself uses. Confirm it with python3 -c "import sys; print(sys.executable)" inside the QGIS Python Console, and build the environment from exactly that path.

How do I check which interpreter a script is actually using? Print sys.executable at the top of the script. It is the single most useful diagnostic line in PyQGIS environment work, because almost every import problem reduces to the answer being different from what you assumed.

Do plugins run in my virtual environment? No. Plugins run inside the QGIS process using the QGIS interpreter, so a dependency installed only in your environment will not be importable from a plugin. Vendor small pure-Python dependencies inside the plugin package, or document the installation step.

Is conda a reasonable way to manage this? Yes — the conda-forge QGIS package installs QGIS and its Python together in one environment, which sidesteps the bindings problem entirely. The trade-off is that the QGIS build is conda's rather than your distribution's, which occasionally matters for plugin compatibility.

Should the environment live inside the project directory? It is convenient and easy to recreate, provided the directory is excluded from version control and from any plugin package you build. A stray environment inside a plugin ZIP is a large upload and an immediate review rejection.