Changes to the plugin engine in 0.6.0 and 0.7.0#
In napari 0.6.0 we have made some changes to napari’s default behaviour when validating legacy “npe1” plugins. This document explains those changes and how they may affect plugin users.
Context#
In mid-2022, we released npe2 - a new napari plugin engine. Mostly invisible to users, npe2 changed the way plugins are built, and how they declare contributions to napari. Because many plugins were already released using the original plugin engine, we continued maintaining all code relating to npe1 plugins, to give developers time to migrate. We also provided guides and utilities for auto-converting npe1 plugins to the new plugin engine.
Through these robust conversion utilities, the vast majority of npe1 plugins can be automatically loaded by napari in an npe2-compatible form, without any changes required from the plugin developer. By enabling the Preferences -> Plugins -> Use npe2 adaptor setting, users could also make their own napari installation auto-convert plugins to the new plugin engine. Before 0.6.0, this setting was off by default; in 0.6.0, this setting will be on by default. In 0.7.0, this setting will be removed entirely, and only auto-convertable plugins will be usable.
In the intervening years, adoption of npe2 has improved, and currently, more than 80% of napari plugins are defined using the npe2 engine. As a result, we have deprecated the npe1 plugin infrastructure, so that we can simplify our codebase and improve maintainability.
What is changing in 0.6.0?#
In napari 0.6.0:
the
Use npe2 adaptorsetting will be turned on by default.if a plugin is still declared using the npe1 engine, napari will auto-convert it to npe2 before loading it.
users will be notified about any auto-converted plugins when launching napari.
if there is a conflict with a plugin, the
Use npe2 adaptorsetting may be disabled. This will allow plugins to be loaded using the original npe1 plugin engine.
What is changing in 0.7.0#
In napari 0.7.0
The
Use npe2 adaptorsetting will be removed.if a plugin is still declared using the npe1 engine, napari will auto-convert it to npe2 before loading it.
There will be no warning dialog about npe1 plugins
How do I know if a plugin is npe1?#
It will show up in the plugin warning dialog in
napari>=0.6.0andnapari<=0.7.0.It will be listed in the plugin manager with an
npe2 (adapted)tag, ifUse npe2 adaptoris checked, or without any tag ifUse npe2 adaptoris not checked (screenshots below)Note that for
napari>=0.7.0it will always be listed with thenpe2 (adapted)tag
It is on this list of plugins. Please note that not all plugins may be listed here.
How does this affect plugins?#
The vast majority of plugins will be unaffected by changing the default behavior in 0.6.0, and users will see minimal, if any, changes.
There are two known cases where autoconversion may be inadequate:
Plugins that performed some action on napari start-up will not do so, as their code is no longer imported on start-up. Instead, the “start-up” behaviour will occur when the user first interacts with any of the plugin’s contributions e.g. if they open a plugin widget, or open a file using the plugin.
Plugin “multi-layer writers” cannot be auto-converted. Multi-layer writers are plugin contributions that allow multiple selected layers to be saved. If an adapted npe1 plugin declares a multi-layer writer, you will see a warning when loading the plugin.
In either of these cases, you can recover original plugin behaviour by going to Preferences -> Plugins and unchecking the Use npe2 adaptor setting, and restarting napari, as directed. Note that this setting is deprecated and will no longer be available in 0.7.0. In the 0.7.0 release only npe2-compatible plugins will be supported.
What can I do if a plugin I use is affected?#
If you’re a napari user, reach out to the plugin developer and ask for the plugin to be updated to npe2. You can typically find the plugin’s GitHub page by clicking on the plugin’s title in the napari plugin manager, and open an issue there. If you’re struggling to find the right place to ask, you can send a message in the napari plugins zulip channel and we will do our best to guide you.
If you’re a plugin developer, you should convert your plugin to npe2. There is an automated utility for converting your plugin, or you can look at the migration guide and contribution guides for more information on manually converting. You can also look at the plugin template for an example of a fully-working npe2 plugin. If your plugin is already npe2, consider adding an npe2 badge: 
.