QGIS Plugin Manager

QGIS Plugin Manager is a professional, high-performance CLI tool designed to manage the full lifecycle of QGIS plugins. From local development and smart synchronization to official repository compliance and automated versioning. Now available on PyPI for easy integration.

✨ Features

⚡ Smart Synchronization

Deploy with idempotent, rsync-like sync: only changed files are copied (size first, then content when sizes match, so same-size rewrites are detected), and files removed from the source are cleaned up in the target. No more slow "delete and copy".

qgis-manage deploy

🗄️ Backup Rotation & Multi-profile

Every deploy creates a timestamped backup of the previous installation, with automatic rotation to keep only the N most recent. Target specific profiles or QGIS versions.

qgis-manage deploy --profile production --qgis-version 4
qgis-manage deploy --purge-backups
qgis-manage deploy --trust   # allow project hooks to execute

🪝 Native Python Hooks

Automate your workflow in pure Python via plugin_hooks.py — or shell commands. Hooks receive full project context (metadata, paths, profiles), run with a 300 s timeout and a minimal environment, and require --trust during deploy.

Trust: hooks are project-controlled code. deploy skips them unless you pass --trust; hooks test is always explicit. Hook commands are bounded to 300 s and receive a minimal environment. Hooks run as argv (no shell) by default; use HookPolicy(shell=True) explicitly for shell syntax.

# plugin_hooks.py
def pre_deploy(context):
    print("Deploying to", context["target_path"])

def post_deploy(context):
    print("Deployed", context["metadata"]["name"])

qgis-manage hooks list
qgis-manage hooks test pre_deploy

🎨 Resource & UI Compilation

Compile .ui (pyuic), .qrc (rcc), and .ts (lrelease) files — with dynamic tool detection and QGIS-compatible import patching — plus Sphinx documentation.

qgis-manage compile
qgis-manage compile --jobs 4   # opt-in parallel UI/QRC/TS compilation

🔢 Automated Versioning

Bump versions across pyproject.toml and metadata.txt with a single command.

qgis-manage bump patch
qgis-manage bump sync

📦 Packaging, Stamping & Compliance

Build repo-ready ZIPs, run compliance checks before upload, and stamp build metadata (git SHA, commit number, datetime, experimental) into metadata.txt.

qgis-manage package --repo-check --sync-version --stamp

Dependencies: if [tool.qgis-manager].dependencies is declared, package requires --trust before installing them.

✅ Deep Validation

Validate metadata and project structure against the official QGIS repository rules — catch errors before you upload.

qgis-manage validate --strict --repo

🌍 Smart Path Detection

Automatically detects the QGIS plugins directory across Linux, macOS and Windows for QGIS 3 and 4, with an interactive fallback when the profile does not exist.

📖 Structured Help

Every command ships a structured --help (usage, options, examples), and the full reference is generated into the help/ directory.

📦 Installation

Requires Python 3.11+.

Install system-wide using uv (recommended):

uv tool install qgis-manage

Or add as a dev-dependency:

uv add --group dev qgis-manage

Or using pip:

pip install qgis-manage

📖 Help

Every command provides a structured --help output with usage, options, and examples.

$ qgis-manage --help

qgis-manage v0.14.0
QGIS Plugin Manager - Modern CLI for plugin development.

Usage: qgis-manage [-h] ... SUBCOMMAND ...

Subcommands:
  deploy      Deploy the plugin to the local QGIS profile
  compile     Compile resources, UI files and translations
  package     Create distributable ZIP package
  ...

General Options:
  -h, --help    show this help message and exit
  ...

Examples:
    # Initialize a new processing plugin
    qgis-manage init "My Plugin" --author "Tester" ...

Full documentation and error reports at: https://github.com/geociencio/qgis-plugin-manager

The full command reference is also available as static Markdown files in the help/ directory. Regenerate them with make help.

🛠️ Command Reference

1. Project Initialization

Scaffold a professional plugin project from a template: default, processing, or dockwidget.

# Create a processing plugin
qgis-manage init "My Plugin" --author "Tester" --email "test@test.com" --template processing

# Create a dockwidget plugin
qgis-manage init "My Plugin" --template dockwidget

2. Development & Deployment

Speed up your local iteration with QGIS 3 and QGIS 4 support.

# Smart deploy to default QGIS 3 profile
qgis-manage deploy

# Deploy to QGIS 4 profile
qgis-manage deploy --qgis-version 4

# Deploy to a specific profile
qgis-manage deploy --profile production

# Run trusted project hooks during deploy
qgis-manage deploy --trust

# Purge old backups to save space
qgis-manage deploy --purge-backups

💡 Smart Path Detection: qgis-manage automatically detects your plugins directory across Linux, macOS, and Windows. If a profile doesn't exist, it will interactively ask if you want to create it or specify a custom location.

3. Resource Compilation (compile)

Compile Qt resources, UI files, translations, and documentation.

# Compile .ui, .qrc, .ts and docs
qgis-manage compile

# Compile only translations
qgis-manage compile --type translations

# Compile up to four files concurrently (default: 1)
qgis-manage compile --jobs 4

4. Advanced Hooks (hooks)

Manage and test your native Python hooks.

# List all hooks from pyproject.toml and plugin_hooks.py
qgis-manage hooks list

# Initialize a standard plugin_hooks.py template
qgis-manage hooks init

# Test a hook in isolation without deploying
qgis-manage hooks test pre_deploy

5. Automated Versioning (bump)

Keep your versions in sync across all project files.

# Increment version (Patch, Minor, Major)
qgis-manage bump patch   # 0.1.0 -> 0.1.1
qgis-manage bump minor   # 0.1.1 -> 0.2.0

# Sync metadata.txt from pyproject.toml source of truth
qgis-manage bump sync

6. Packaging & Compliance

Prepare for the Official QGIS Plugin Repository.

# Create a "Repo-Ready" ZIP package
qgis-manage package

# Package with strict compliance check and post-build ZIP audit
qgis-manage package --repo-check --sync-version

# Validate an already-built ZIP (root, metadata, LICENSE, size, modes)
qgis-manage validate --zip dist/demo_plugin.1.0.0.zip --strict-permissions
qgis-manage validate --zip dist/demo_plugin.1.0.0.zip --max-size-mb 25 --icon-min-px 32
qgis-manage validate --zip dist/demo_plugin.1.0.0.zip --json

# Allow declared dependencies to be installed while packaging
qgis-manage package --trust

# Stamp git build info (commit SHA, commit number, datetime, experimental)
qgis-manage package --stamp

7. Maintenance & Quality

# Run deep structural validation
qgis-manage validate --strict --repo

# Run QGIS Plugin Analyzer on the project
qgis-manage analyze

# Run a security audit (secrets and PyQGIS rules)
qgis-manage security --strict

# Install plugin dependencies into a local folder
qgis-manage install-deps --target libs
qgis-manage install-deps --dry-run   # print the installer command only
qgis-manage install-deps --timeout 120

# Clean caches, compiled UI/resources and docs output
qgis-manage clean

# Remove the deployed plugin from the QGIS profile
qgis-manage dclean

Note: analyze and security rely on qgis-plugin-analyzer, available via the dev extra (uv add --group dev qgis-plugin-analyzer).

⚙️ Configuration (pyproject.toml)

Leverage YOUR existing configuration. No new files needed. Current project version: 0.14.0 (Python 3.11+).

[tool.qgis-manager]
qgis_version = 4  # Target QGIS 4 by default
max_backups = 5   # Control backup rotation
profile = "default"
docs_entry = "help/html/index.html"  # or "help/html/*/index.html"
max_package_size_mb = 25
icon_min_px = 32
normalize_permissions = true

ignore = [
    "data/*.csv",
    "tests/temp/*",
    "!tests/temp/keep.csv"
]

[tool.qgis-manager.hooks]
post_deploy = "python scripts/notify.py"

Nested .qgisignore/.gitignore files apply to their subtree; deeper rules and !negations win. External commands can be registered through the qgis_manager.commands entry-point group.

🌍 Internationalization (i18n)

Automated compilation and management of .ts and .qm translation files is handled by the compile command (see the Command Reference above).

📄 License

GPL-2.0-or-later