Skip to content

Plugin migration to QGIS 3

Jump to bottom Edit New page
Étienne Trimaille edited this page Sep 11, 2019 · 38 revisions

Recommendations

  • 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 https://qgis.org/pyqgis/master/gui/index.html. It's less code to write for you, and users will have the same user experience across plugins and QGIS Desktop.

  • Use from qgis.PyQt.QtCore import QDir for instance instead of from PyQt5.QtCore import QDir in your code. So it's less code to update when QGIS will use a newer Qt version. It works for other Qt modules.

  • 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: http://www.geopackage.org

  • 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 github.com/opengisch/qgis2to3)
  • 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.
  • without qgis2to3, using 2to3 from QGIS source tree, located in path/to/QGIS/scripts/2to3. Follow instructions from qgis2to3
  • 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: https://github.com/qgis/QGIS/pull/5904)

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

Common migration issues

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: https://www.lutraconsulting.co.uk/blog/2016/06/12/introducing-first-aid-plugin/

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

wiki footer here

Add a custom sidebar
Clone this wiki locally