pb_tool

A command-line tool for building and deploying QGIS Python plugins. pb_tool handles compiling UI and resource files, building Sphinx documentation, managing translations, deploying to your local QGIS plugin directory, and packaging for the QGIS Plugin Repository.

Supports QGIS 3 and QGIS 4, Qt5 and Qt6, and runs on Linux, macOS, and Windows.

Features

Scaffold a new plugin from a processing, dialog, or dockwidget template
Compile .ui and .qrc files (auto-detects pyuic5/pyuic6 and rcc)
Deploy to your QGIS plugin directory for live testing
Package into a .zip for upload to the Plugin Repository
Build and clean Sphinx HTML documentation
Compile translation files with lrelease
Clean compiled and deployed files
Validate your config file and environment

Installation

pip install pb_tool

To upgrade:

pip install --upgrade pb_tool

pb_tool is also available as the shorter alias pbt:

pbt deploy

Runtime dependencies

Tool	Purpose
`pyuic5` or `pyuic6`	Compile `.ui` files to Python
`rcc`	Compile `.qrc` resource files
`lrelease`	Build `.qm` translation files from `.ts` sources
`zip` or `7z`	Package the plugin for upload
`sphinx` + `make`	Build HTML help documentation

Configuration

pb_tool requires a pb_tool.cfg file in your plugin's root directory. Plugin Builder generates this automatically. You can also create one by hand using the template below.

[plugin]
# Directory name used when deploying to the QGIS plugins folder
name: MyPlugin

# Override the deploy path (leave empty to use the QGIS default location)
plugin_path:

[files]
# Python source files to deploy
python_files: __init__.py my_plugin.py my_plugin_dialog.py

# Main dialog .ui file — loaded at runtime, not compiled
main_dialog: my_plugin_dialog_base.ui

# Additional .ui files to compile to Python
compiled_ui_files: settings_dialog.ui

# Qt resource files (.qrc) to compile
resource_files: resources.qrc

# Other files to include (e.g. metadata.txt, icon.png)
extras: metadata.txt icon.png

# Files to exclude from deployment (glob patterns, space-separated)
excluded_files:

# Subdirectories to deploy alongside the plugin
extra_dirs: i18n

# Locales to build — .ts files must exist in the i18n/ directory
locales: en.ts fr.ts

[help]
# Sphinx build output directory
dir: help/build/html
# Directory name inside the deployed plugin
target: help

All paths are relative to the directory where you run pb_tool. The name value must match the folder name used in the QGIS plugins directory.

Resource files: `os.path` vs `rcc` compilation

QGIS plugins can reference external assets (icons, images) in two ways:

Preferred — os.path (filesystem paths):

icon_path = os.path.join(os.path.dirname(__file__), 'icon.png')
icon = QIcon(icon_path)

Assets are deployed as plain files alongside the plugin and referenced by absolute path at runtime. No compilation step required, no Qt resource system dependency, and the files are visible to the OS like any other file.

Alternative — rcc compiled resources:

import resources_rc  # generated by rcc from resources.qrc
icon = QIcon(':/plugins/my_plugin/icon.png')

Assets are compiled into a Python module (resources_rc.py) and embedded using Qt's virtual filesystem (:/ prefix). This requires rcc at build time and pb_tool compile before each deploy.

Plugin Builder and pb_tool use the os.path approach. If you have a .qrc file and prefer the compiled approach, list it under resource_files in pb_tool.cfg and run pb_tool compile — both workflows are supported.

Commands

Run pb_tool --help for the full command list. Commands support unique-prefix abbreviation — pb_tool dep is the same as pb_tool deploy.

`create`

Create a new plugin skeleton from a template, with a pb_tool.cfg already configured.

pb_tool create [OPTIONS]

Option	Default	Description
`--type`	`processing`	Plugin type: `processing`, `dialog`, or `dockwidget`
`--name`	prompted	Module name (snake_case) — used as the output directory
`--class_name`	prompted	Class name (CamelCase)
`--title`	prompted	Human-readable title shown in QGIS menus
`--description`	prompted	Short plugin description
`--author`	prompted	Author name
`--email`	prompted	Author email

All options are optional. Any omitted value is collected interactively. The plugin files are written to a new subdirectory named after --name.

Example:

pb_tool create --type dialog --name my_plugin --class_name MyPlugin

Generated files vary by type:

processing — __init__.py, <name>.py, <name>_provider.py, <name>_algorithm.py, icon.png, pb_tool.cfg
dialog — __init__.py, <name>.py, <name>_dialog.py, <name>_dialog_base.ui, icon.png, pb_tool.cfg
dockwidget — __init__.py, <name>.py, <name>_dockwidget.py, <name>_dockwidget_base.ui, icon.png, pb_tool.cfg

After running, add a metadata.txt and then use pb_tool deploy to install the plugin.

`deploy`

Compile files, build docs, and copy everything to the QGIS plugin directory.

pb_tool deploy [OPTIONS]

Option	Description
`--config_file FILE`	Config file to use (default: `pb_tool.cfg`)
`-p, --plugin_path PATH`	Override the deploy destination
`-q, --quick`	Skip compiling and doc building; copy files only
`-y, --no-confirm`	Skip the confirmation prompt
`-n, --no-docs`	Skip building Sphinx documentation

A full deploy will:

Remove the currently deployed version (dclean)
Compile all UI and resource files
Build Sphinx HTML documentation
Copy all declared files and directories to the plugin folder

Use -q for fast iteration when you only changed Python files.

Example output:

Deploying will:
    * Remove your currently deployed version
    * Compile the ui and resource files
    * Build the help docs
    * Copy everything to your ~/.local/share/QGIS/QGIS4/.../plugins/MyPlugin directory

Proceed? [y/N]: y
Removing plugin from ...
Compiling to make sure install is clean
Skipping resources.qrc (unchanged)
Building the help documentation
...
Copying __init__.py
Copying my_plugin.py
...

`compile`

Compile .ui and .qrc files without deploying.

pb_tool compile [--config pb_tool.cfg]

Detects pyuic6 first, falls back to pyuic5
Uses rcc for resource files; automatically rewrites PySide6 imports to qgis.PyQt
Skips files that have not changed since the last compile

`doc`

Build Sphinx HTML documentation.

pb_tool doc

Runs make html inside the help/ directory. Requires a Sphinx project set up there (Plugin Builder creates this automatically).

`translate`

Compile .ts translation files to .qm using lrelease.

pb_tool translate [--config pb_tool.cfg]

Locales must be listed under [files] > locales in your config, and the .ts files must exist in the i18n/ directory.

`zip`

Package the deployed plugin into a .zip suitable for the QGIS Plugin Repository.

pb_tool zip [--config_file pb_tool.cfg] [-q]

By default triggers a full dclean + deploy first. Use -q to skip that step if the plugin is already deployed and current.

Requires zip or 7z on your PATH.

`validate`

Check pb_tool.cfg for required fields and report the environment status.

pb_tool validate [--config_file pb_tool.cfg]

Reports:

Whether all mandatory config keys are present
Resolved QGIS plugin directory path
Python version in use
Whether a suitable zip utility was found

`clean`

Delete compiled UI and resource .py files.

pb_tool clean [--config pb_tool.cfg]

`clean_docs`

Remove the built Sphinx HTML output.

pb_tool clean_docs

`dclean`

Remove the deployed plugin from the QGIS plugins directory (prompts for confirmation).

pb_tool dclean [--config pb_tool.cfg]

`list`

Print the contents of the config file.

pb_tool list [--config_file pb_tool.cfg]

`config`

Generate a pb_tool.cfg by scanning source files in the current directory. Useful for adding pb_tool to an existing plugin that wasn't created with pb_tool create.

pb_tool config [--name pb_tool.cfg] [--package PACKAGE_NAME]

Option	Default	Description
`--name`	`pb_tool.cfg`	Output filename
`--package`	prompted	Plugin package name (lowercase, used as the deployment directory name)

Scans the current directory for .py, .ui, .qrc, .png, metadata.txt, and i18n/*.ts files and populates the config from them. If writing to pb_tool.cfg (the default), it warns before overwriting.

`update`

Check whether a newer version of pb_tool is available.

pb_tool update

`version`

Print the current pb_tool version and exit.

pb_tool version

Plugin directory detection

pb_tool automatically resolves the QGIS plugin directory in this order:

Linux / macOS:

~/.local/share/QGIS/QGIS4/profiles/default/python/plugins
~/.local/share/QGIS/QGIS3/profiles/default/python/plugins

Windows:

%APPDATA%\QGIS\QGIS4\profiles\default\python\plugins
%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins

If neither path exists, the QGIS 4 path is used as the default. Override at any time with deploy -p /your/path.

Typical workflow

# Create a new plugin skeleton
pb_tool create --type processing --name my_plugin --class_name MyPlugin

# First deploy — full compile + copy
pb_tool deploy

# Iterate quickly on Python changes only
pb_tool deploy -q

# Validate your config and environment
pb_tool validate

# Package for the Plugin Repository
pb_tool zip

# Clean up compiled artefacts
pb_tool clean

Troubleshooting

pyuic5/pyuic6 not found — install Qt development tools. On Ubuntu/Debian: sudo apt install pyqt5-dev-tools or sudo apt install pyqt6-dev-tools. On Windows, install via OSGeo4W.

rcc not found — install the Qt resource compiler. On Ubuntu/Debian: sudo apt install qtbase5-dev-tools or sudo apt install qt6-base-dev-tools.

Pygments uninstall error on pip install — run:

pip install --ignore-installed Pygments pb_tool

Windows setup — see PyQGIS Developer Cookbook: Introduction for current PATH and PYTHONPATH configuration on Windows.

Contributing

Issues and pull requests: https://github.com/jonah-sullivan/plugin_build_tool

License

GNU General Public License v2 or later (GPLv2+).

Name		Name	Last commit message	Last commit date
Latest commit History 113 Commits
.github/workflows		.github/workflows
docs		docs
pb_tool		pb_tool
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
test_pb_tool.py		test_pb_tool.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

pb_tool

Features

Installation

Runtime dependencies

Configuration

Resource files: `os.path` vs `rcc` compilation

Commands

`create`

`deploy`

`compile`

`doc`

`translate`

`zip`

`validate`

`clean`

`clean_docs`

`dclean`

`list`

`config`

`update`

`version`

Plugin directory detection

Typical workflow

Troubleshooting

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

pb_tool

Features

Installation

Runtime dependencies

Configuration

Resource files: os.path vs rcc compilation

Commands

create

deploy

compile

doc

translate

zip

validate

clean

clean_docs

dclean

list

config

update

version

Plugin directory detection

Typical workflow

Troubleshooting

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Resource files: `os.path` vs `rcc` compilation

`create`

`deploy`

`compile`

`doc`

`translate`

`zip`

`validate`

`clean`

`clean_docs`

`dclean`

`list`

`config`

`update`

`version`

Packages