Plugin migration to QGIS 3

Jonathan Willitts edited this page Oct 10, 2018 · 35 revisions

While you are porting/rewriting your plugin, think about using QGIS native widgets. For instance, if you need a combobox providing a list of layers, use a QgsMapLayerComboBox instead of a QComboBox. There is also QgsFieldComboBox if you need to pick a field in a vector layer. The full list of widgets is here It's less code to write for you, and users will have the same user experience across plugins and QGIS Desktop.

Also think about using the Processing framework. Your plugin can become its own Processing provider so your algorithms can be included in models and have the same UI as native algorithms. It's also less code to write, the UI is managed by QGIS. In QGIS 3, Processing has been refactored and is much more powerful than in QGIS 2.

In QGIS 3, GeoPackage is much more present. Avoid creating shapefile in your plugin if possible and use the OGC standard GeoPackage format which can store both raster and vector in a single file:

Note that you can easily provide one version for QGIS 2 and QGIS 3 at the same time. Fill you metadata.txt correctly with qgisMinimumVersion and qgisMaximumVersion. The plugin manager will automatically ship the highest version based on the QGIS version.

Plugin location on file system

While in QGIS 2, plugins were located in your home directory in the .qgis2/python/plugins folder. In QGIS 3, this folder is now in a specific QGIS profile. You can find this folder by going to Settings -> User profiles -> Open Active Profile folder. You will find python/plugins.

Minimal info

  • pip install future
  • pip install qgis2to3 (docs
  • qgis2to3 /path/to/my/plugin
    • This command will print the diff. If you want to write these changes to files, use -w
    • The script will automatically update from Py2 to Py3, from Qt4 to the correct PyQt version. For instance from PyQt4.QtGui import QMainWindow will become from qgis.PyQt.QtWidgets import QMainWindow.
    • The command will update some QGIS API changes.
  • qgis2apifinder /path/to/my/plugin
  • set qgisMinimumVersion=3.0 in metadata.txt
  • make sure you do python3 and Qt5!
  • tweak and fix until it works :-)

You should see your plugin in QGIS 2.99 and up (note: if it does not appear, make sure your build is newer than 4.01.2018, as there was an important change 3.01.2018 17:09 UTC:

You can find Python API documentation at Please note: QGIS3 compatibility module (so 3.x plugins will also work on 2.18) has been deprecated.

Debugging and finding problems

You can use the qgis2to3 tools and your IDEs (PyCharm or Eclipse) to step through your code and find and solve incompatibilities. Alternatively, you can install First Aid plugin and use it within QGIS. More info can be found here:

Other possible issues Python plugin issues and tips

  • MetaSearch user migration: problems with Python plugins? Clear out your *.pyc files (so QGIS Python can compile via Python 3).
  • QuickOSM migration: At the beginning of the migration, Plugin reloader couldn't work with my plugin. I was using the plugin manager to enable/disable the plugin. It was reloading the plugin, instead of relaunching QGIS.

More info

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.