Most publicly available QGIS plugins are hosted in the official repository . However, in some cases there is a need to create your own plugin repository, for example, to distribute your plugin in a narrow circle of colleagues of a particular organization. In this article we will look at how to implement our own plugin repository, and also discuss the minimum requirements that a plug-in must meet in order to place it in its own repository.Note 2, , QGIS 3.10.5 LTR.
Plugin Manager
QGIS has a special tool for working with plugins - the plugin manager. It allows you to search for plugins, install and remove them, track the appearance of new versions of installed plugins, connect third-party repositories, etc. For each plugin, the plugin manager provides a window with information about the plugin. There are three scenarios for filling this information:- The plugin is in the repository, but not installed on your computer. In this case, all information for the plugin manager is extracted from the plugin description in the plugins.xml file.
- The plugin is installed on your computer and there is a connection with the repository. In this case, part of the information is still extracted from the plugin description in the plugins.xml file, and part from the metadata file metadata.txt
- The plugin is installed on your computer and there is no connection with the repository. In this case, all information for the plugin manager is extracted from the metadata file metadata.txt.
The table below describes where the parameters come from in the window with information about the plugin, in each of three cases:- , QGIS, metadata.txt plugins.xml . initGui() .
- Installed version Available version, QGIS . Installed version Available version, QGIS «Installed version of this plugin is higher than any version found in repository». , , .
- , metadata.txt plugins.xml . .
- Available version plugins.xml version pyqgis_plugin, version.
- metadata.txt plugins.xml Experimental Deprecated, .
- QGIS (QgisMinimumVersion) (QgisMaximumVersion) , metadata.txt plugins.xml.
- , . , QgisMinimumVersion + 0.99.
- __init__.py is the starting point of the plugin. The file must contain the classFactory () method.
- metadata.txt - contains general information about the plugin.
An example of a plugin with a minimal set of files can be found here .You can study the structure of plugins in more detail in the official documentation .Metadata file
As already noted, in the directory of each plugin there must be a metadata.txt file containing general information about the plugin. The information from it is used to display in the QGIS plugin manager, search for a plugin, etc.The metadata file structure should be as follows:[general]
Parameter1_Name: Parameter1_Value
Parameter2_Name: Parameter2_Value
…
ParameterN_Name: ParameterN_Value
Or:[general]
Parameter1_Name= Parameter1_Value
Parameter2_Name= Parameter2_Value
…
ParameterN_Name= ParameterN_Value
You can use either a colon or the "=" symbol as a separator for the parameter name and its value. However, it is not necessary that there is only one type of delimiter in a single metadata file. Spaces before and after the separator do not affect the reading of data from metadata.txt, therefore, they can be in any quantity or absent altogether. Note also that the keyword "[general]" at the beginning of the metadata file is required.The required parameters, without which the plug-in may be interrupted, are as follows:- name - name of the plugin,
- version - plugin version,
- qgisMinimumVersion is the minimum version of QGIS suitable for working with this plugin.
You can find out information about other parameters here .plugins.xml
Each repository should contain a plugins.xml file that provides general information for the plugin manager about all the plugins available in the repository.The structure of plugins.xml should be as follows:<plugins>
<pyqgis_plugin name="Plugin1_Name" version="Plugin1_Version">
<Plugin1_Parameter1_Name>Plugin1_Parameter1_Value</Plugin1_Parameter1_Name>
<Plugin1_Parameter2_Name>Plugin1_Parameter2_Value</Plugin1_Parameter2_Name>
....
<Plugin1_ParameterN_Name>Plugin1_ParameterN_Value</Plugin1_ParameterN_Name>
</pyqgis_plugin>
...
<pyqgis_plugin name="PluginN_Name" version="PluginN_Version">
<PluginN_Parameter1_Name>PluginN_Parameter1_Value</PluginN_Parameter1_Name>
<PluginN_Parameter2_Name>PluginN_Parameter2_Value</PluginN_Parameter2_Name>
....
<PluginN_ParameterN_Name>PluginN_ParameterN_Value</PluginN_ParameterN_Name>
</pyqgis_plugin>
</plugins>
The required parameters without which the repository may be interrupted are the following:- name - the name of the plugin (indicated as a parameter of the pyqgis_plugin tag)
- version - version of the plugin (specified as a parameter of the pyqgis_plugin tag),
- qgis_minimum_version - the minimum version of QGIS suitable for working with this plugin,
- download_url - url where the zip archive with your plugin is located.
It is recommended to study the example plugins.xml file from the official QGIS repository (replace the numbers at the end of the link with the version of QGIS installed on your computer).The relationship between the local plugin and the plugin in the repository
How does the plugin manager understand that a certain plugin installed on your computer and a plugin in the connected repository are the same plugin, for example, in order to check if a new version of the plugin has appeared in the repository?Without going into technical details, the rule for connecting plugins is as follows: the local plug-in and the plug-in in the repository are considered by the QGIS plug-in manager to be the same plug-in if the name of the plug-in root folder matches either the text up to the first point from the file_name tag, or if the file_name tag is missing, with text to the first point of the last path element from the download_url tag.In other words, if the file_name tag is present in the plugin description from plugins.xml, then the part to the first point (highlighted in bold) will be extracted from it, which must be exactly the name of the root folder of the installed plugin so that the QGIS plugin manager considers them to be one and the same plugin. If the file_name tag is missing, the last path element from the download_url tag will be parsed in the same way. The part extracted from it to the first point (highlighted in bold) must also be exactly the name of the root folder of the installed plug-in so that the QGIS plug-in manager considers them to be the same plug-in. If there is no match between the name of the root folder and the extracted part from file_name, or (if file_name is missing) from download_url, then the plugins are considered different plugins.<file_name>PluginName.2.1.0.zip</file_name><download_url>YourRepositoryURL/PluginName.2.1.0.zip</download_url>Considering this rule, it is recommended to add the file_name tag in the plugins description in the plugins.xml file, which does not indicate the name of your zip archive, but the name of the root folder of your plugin, to which you can optionally add a version or other information, separating them with a dot. In this case, you can name the zip archive with the plugin as you like, including by separating the name of the plugin and its version with a hyphen, as is customary in the official repository.Examples of correctly designed plugins
Example 1
Plugin File Structure
FolderName.SomeInfo.zip
---FolderName
------__init__.py
------metadata.txtMetadata.txt file
[general]
name: PluginName
version: 2.1.0
qgisMinimumVersion: 3.0Plugins.xml file
<plugins>
<pyqgis_plugin name="PluginName" version="2.1.0">
<qgis_minimum_version>3.0.0</qgis_minimum_version>
<download_url>YourRepositoryURL/FolderName.SomeInfo.zip</download_url>
</pyqgis_plugin>
</plugins>
In this example, the connection between the plugin installed locally on your computer and the plugin in the repository is through the name of the root folder and the download_url tag. Therefore, the part of the name of the zip archive to the first point and the name of the root folder of the plugin must match exactly.Example 2
Plugin File Structure
ArchiveName.SomeInfo.zip
---FolderName
------__init__.py
------metadata.txtMetadata.txt file
[general]
name: PluginName
version: 2.1.0
qgisMinimumVersion: 3.0Plugins.xml file
<plugins>
<pyqgis_plugin name="PluginName" version="2.1.0">
<qgis_minimum_version>3.0.0</qgis_minimum_version>
<file_name>FolderName.SomeInfo</file_name>
<download_url>YourRepositoryURL/ArchiveName.SomeInfo.zip</download_url>
</pyqgis_plugin>
</plugins>
In this example, the connection between the plugin installed locally on your computer and the plugin in the repository is through the name of the root folder and the file_name tag. In this case, the part of the name of the zip archive to the first point and the name of the root folder may differ.Create Repository
The QGIS plugin repository should consist of a plugins.xml file that provides general information for the plugin manager about all plugins available in the repository and zip archives containing the plugins themselves. The repository can be hosted on web services such as GitHub or Bitbucket.An important requirement for QGIS to recognize such a repository is to access files through a direct link. This can be done, for example, using Github Pages or Bitbucket Pages. Google Drive or DropBox will not work for these purposes. they do not allow a direct link to a file of the form ... / filename.extension.Instructions for using GitHub to host a static website are located here .Instructions on how to use Bitbucket to host a static website are located here .As a rule, you just need to rename your repository according to the template:username.imtqy.com (for GitHub)orusername.bitbucket.io (for Bitbucket)After the necessary settings, the link to your QGIS repository will look like this:username.imtqy.com/plugins.xml (for GitHub)orusername.bitbucket.io/plugins.xml(for Bitbucket)This link must be specified in the URL field in the QGIS plugin manager when connecting a new repository. If the connection to the repository is successful, then the status of the repository will be set to “connected”, and the plugins described in the plugins.xml file will appear in the list of available plugins.