Exercise 1: initial plugin with copier template - rnousia/example-plugin-for-quc2026 GitHub Wiki

Step 1: Install uv

Install uv as a standalone tool.

BACKUP: If cannot install as a standalone...

If there is no system python installed (e.g. if Windows is used), QGIS python can be used to make virtual environment for the next step. Create a parent directory for the workshop plugin first:

mkdir quc-2026-workshop
cd quc-2026-workshop

Create a python virtual environment (this can be created without --system-site-packages flag as we don't need the QGIS libraries here):

C:\<QGIS installation directory>\apps\Python312\python.exe -m venv .venv-tools

QGIS installation directory is typically either C:/Program Files/QGIS x.x or C:/OSGeo4W/

Activate and install uv:

.venv-tools\Scripts\activate
pip install uv

Step 2: Create QGIS-aware Python virtual environment using qgis-venv-creator

Create a new folder where the example plugin will be created from template and navigate to the created folder:

mkdir quc-2026-workshop-plugin
cd quc-2026-workshop-plugin

Run the following command to create a virtual environment which is aware of the QGIS libraries. The qgis-venv-creator tool should find all QGIS installations available in your system to choose from:

uvx --from qgis-venv-creator create-qgis-venv

Tip

With Linux, you can also run just:

python -m venv --system-site-packages

With Mac OS run the following instead:

uvx --from git+https://github.com/cofactor-company/qgis-venv-creator@mac-support-2 create-qgis-venv

Step 3: Create a QGIS plugin from template

Use the qgis-plugin-copier-template to create a base for a QGIS plugin (we have already installed necessary tools so only copier copy is needed):

uvx copier copy --answers-file .copier-answers.qgis-plugin.yml https://github.com/osgeosuomi/qgis-plugin-copier-template.git . --data qgis_plugin_name="Painter Plugin" --data qgis_plugin_class=PainterPlugin --data qgis_plugin_module=painter_plugin --data qgis_plugin_description="Workshop example" --data qgis_plugin_about="Workshop example" --data qgis_version=QGIS3 --data setup_translations=true --data type_checking_library=ty --data plugin_metadata_email=workhsop@com --data plugin_metadata_repository_url=https://example-plugin-for-quc2026.github.com --data is_monorepo_component=false --data insert_copyright_header=false --data add_github_workflows=true --data min_code_coverage=80

Afterwards run the recommended commands:

git init
uv sync
uv run prek install

Tip

Installing pre-commit hooks may fail if folder is not yet initialized as a Git repository. In that case, run git init first.

Step 4: Start the plugin

Create .env file by copying the example file:

cp .env.example .env

Edit the file with a text editor:

On Windows 
notepad .env

And set the QGIS_EXECUTABLE_PATH to point out to your QGIS binary.

Tip

On Windows QGIS binary is typically found under C:/Program Files/QGIS x.x/bin or C:/OSGeo4W/bin
On Linux it is typically /usr/bin/qgis
On Mac Os it is typically: `/Applications/QGIS.app/Contents/MacOS/QGIS

Then start the plugin in development mode:

uv run qpdt s
⚠️ **GitHub.com Fallback** ⚠️