Skip to content

How to use the QField plugin templater

The quickest way to generate a QField plugin template is with pipx / uvx:

pipx run cookiecutter gh:gounux/qfield-plugin-templater

uvx cookiecutter gh:gounux/qfield-plugin-templater

You can also install cookiecutter via:

pipx install cookiecutter

uv tool install cookiecutter

Then run the templater:

cookiecutter gh:gounux/qfield-plugin-templater

Note

Consider creating a new empty repository on GitLab or on GitHub, before generating a new QField plugin with the templater. This will directly and properly bind the repository with the generated QField plugin.

CLI usage

You can give arguments to the cookiecutter CLI, to bypass the prompts:

cookiecutter gh:gounux/qfield-plugin-templater "plugin_name=My Topologizer"

Info

You can browse all the possible arguments accepted by the QField plugin templated in the accurate section: template parameters.

If running in a CI, you can give the --no-input option:

cookiecutter gh:gounux/qfield-plugin-templater --no-input "plugin_name=My Topologizer"

Template parameters

When generating a QField plugin template, the following values are asked:

  • plugin_name:

Plugin name, used to populate the metadata.txt file essentially.

Example: My Topologizer

  • plugin_name_slug:

Slugified name, will be used to create the directory for the source code. Default value deduced from the plugin name.

Example: my-topologizer

  • plugin_description:

Plugin description, preferably short.

Example: This QField plugin will make you map the moon!

  • plugin_author:

Plugin author.

Example: Jane Doe

  • plugin_locales:

Comma-separated list of locales to support translations for the plugin. Can also be configured later.

Example: de,es,fr,it

  • ci_platform:

CI platform to configure for this plugin.

Available values: GitHub, GitLab or None

  • repository_url_base:

Base URL of the repository for this plugin.

Example: https://github.com/gounux/my-topologizer/ or https://gitlab.com/gounux/my-topologizer/.

  • open_source_license:

License to use for the plugin.

Available values: GPLv2+, GPLv3, MIT or None