QGIS Venv Creator

Single file and zero dependency tool to create a Python virtual environment for QGIS plugin development.

Table of Contents

• Installation
• Usage
• Development
• License

Installation

The recommended way to install qgis-venv-creator (and other Python cli tools) is to install it with pipx. Pipx will install the application in an isolated environment and make it available as a command line utility. To install pipx, follow the instructions provided at https://github.com/pypa/pipx#install-pipx.

$ pipx install qgis-venv-creator

Alternatively, to install in your current Python environment:

$ pip install qgis-venv-creator

Copy as a script

qgis-venv-creator is a single Python script that can be downloaded and copied to your project root, or any other location from which you wish to use it.

Usage

Quick start

On your plugin root directory, run:

$ create-qgis-venv

Note:
If you have copied the script file to your project root, you can run it with python create-qgis-venv.py.

On a system where there might be multiple QGIS installations (ie. Windows, MacOs), you are asked to select the one you want to use for development.

After the virtual environment is created, you can activate it and it will have access to the QGIS Python environment.

Options

create-qgis-venv [-h] [--venv-parent VENV_PARENT] [--venv-name VENV_NAME]
                    [--qgis-installation QGIS_INSTALLATION]
                    [--qgis-installation-search-path-pattern QGIS_INSTALLATION_SEARCH_PATH_PATTERN]
                    [--python-executable PYTHON_EXECUTABLE] [--debug]

Development

This project uses uv for development and packaging. Install instructions can be found at https://docs.astral.sh/uv/getting-started/installation/.

Create the development environment with:

uv sync

uv creates an in-project .venv, which VS Code picks up automatically as the interpreter.

Common commands:

uv run pytest                        # run unit tests (e2e skipped by default)
uv run pytest tests/unit/test_prompt.py::test_prompt_on_valid_selection   # single test
uv run coverage run -m pytest        # run tests with coverage
uv run coverage report               # print coverage report
uv run ty check src/qgis_venv_creator tests   # type check
uv run ruff check .                  # lint
uv run ruff format .                 # format
uv build                             # build sdist + wheel into dist/

To run the test suite against a specific Python version, pass -p, e.g. uv run -p 3.8 pytest.

The version is bumped with uv version --bump <major|minor|patch> followed by python scripts/sync_version.py, which copies the new version into __version__ in src/qgis_venv_creator/create_qgis_venv.py (tests/unit/test_version.py guards against drift).

Pre-commit hook

This project uses prek to run code checks before committing.

Install pre-commit hooks to your repo with:

uv run prek install

License

qgis-venv-creator is distributed under the terms of the MIT license.