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.

🥇 The "Manager" Difference

qgis-plugin-manager is the modern successor to traditional QGIS development workflows.

📊 Ecosystem Comparison

🚀 Key Differentiators (USPs)

• Smart Synchronization (Sync v2.0): We use idempotent sync logic. Instead of slow "delete and copy", we only update modified files.
• Native Python Hooks Architecture: Write your automation in pure Python via plugin_hooks.py. Hooks receive full project context (metadata, paths, profiles).
• Official Repository "First-Time-Right": Built-in --repo-check and structural validation catch errors before you upload to QGIS.
• Automation-Friendly: Structured --help output and a modular command system make it easy to script and integrate into CI pipelines.

📦 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.8.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 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.

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

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

# 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, translations, and documentation.

# Compile resources, translations and docs
qgis-manage compile

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

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 (fails if binaries or errors found)
qgis-manage package --repo-check --sync-version

7. Maintenance & Quality

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

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

# Install plugin dependencies into a local folder
qgis-manage install-deps --target libs

# Clean Python artifacts (__pycache__) and build files
qgis-manage clean

⚙️ Configuration (pyproject.toml)

Leverage YOUR existing configuration. No new files needed.

[tool.qgis-manager]
qgis_version = 4  # Target QGIS 4 by default
max_backups = 5   # Control backup rotation
profile = "default"

[tool.qgis-manager.ignore]
ignore = [
    "data/*.csv",
    "tests/temp/*"
]

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

🌍 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