Manifest Reference


Plugin manifests are a feature of the second generation napari plugin engine (“npe2”). If you are still using the first generation napari-plugin-engine (i.e. the napari.plugin entrypoint, along with @napari_hook_implementation decorators) then this page does not apply to your plugin.

Every napari plugin needs to ship a manifest file with their package. By convention, this file is called napari.yaml and it is placed in the top level module of the package, but it can be named anything and placed anywhere.

You tell napari where to find your manifest by adding a napari.manifest entry point to your package metadata:

# tell napari where to find to your manifest
napari.manifest =
    example-plugin = example_plugin:napari.yaml

# make sure it gets included in your package
example-plugin = napari.yaml


All fields are optional except those in bold.




The name of the plugin. Though this field is mandatory, it must match the package name as defined in the python package metadata.


User-facing text to display as the name of this plugin. Must be 3-40 characters long, containing printable word characters, and must not begin or end with an underscore, white space, or non-word character. If not provided, the manifest name will be used as the display name.


A SemVer compatible version string matching the napari plugin schema version that the plugin is compatible with.


Fully qualified python path to a function that will be called upon plugin activation (e.g. 'my_plugin.some_module:activate'). The activate function can be used to connect command ids to python callables, or perform other side-effects. A plugin will be ‘activated’ when one of its contributions is requested by the user (such as a widget, or reader).


Fully qualified python path to a function that will be called when a user deactivates a plugin (e.g. 'my_plugin.some_module:deactivate'). This is optional, and may be used to perform any plugin cleanup.


An object describing the plugin’s contributions


Standard python package metadata from your setup.cfg file will also be parsed for version, license, and other info.


Here is a complete example of what the manifest of a plugin providing all contributions might look like. (Note: a plugin needn’t implement more than a single contribution type).


Both YAML and TOML are supported manifest formats, though YAML is the “default” and more common format.

name: example-plugin
display_name: Example Plugin
schema_version: 0.1.0
  - id: example-plugin.hello_world
    title: Hello World
  - id: example-plugin.read_xyz
    title: Read ".xyz" files
    python_name: example_plugin.some_module:get_reader
  - id: example-plugin.write_points
    title: Save points layer to csv
    python_name: example_plugin.some_module:write_points
  - id: example-plugin.my_widget
    title: Open my widget
    python_name: example_plugin.some_module:MyWidget
  - id: example-plugin.do_threshold
    title: Perform threshold on image, return new image
    python_name: example_plugin.some_module:threshold
  - id: example-plugin.threshold_widget
    title: Make threshold widget with magic_factory
    python_name: example_plugin.some_module:widget_factory
  - id:
    title: Create fractal image
    python_name: example_plugin.some_module:create_fractal
  - command: example-plugin.read_xyz
    - '*.xyz'
    accepts_directories: false
  - command: example-plugin.write_points
    - points
    - .csv
  - command: example-plugin.my_widget
    display_name: Wizard
  - command: example-plugin.threshold_widget
    display_name: Threshold
  - command: example-plugin.do_threshold
    display_name: Threshold
    autogenerate: true
  - key: fractal
    display_name: Fractal
  - key: napari
    display_name: Tabueran Kiribati
  - id: monokai
    label: Monokai
    type: dark
      canvas: black
      console: black
      background: '#272822'
      foreground: '#75715e'
      primary: '#cfcfc2'
      secondary: '#f8f8f2'
      highlight: '#e6db74'
      text: '#a1ef34'
      warning: '#f92672'
      current: '#66d9ef'
display_name = 'Example Plugin'
name = 'example-plugin'
schema_version = '0.1.0'

id = 'example-plugin.hello_world'
title = 'Hello World'

id = 'example-plugin.read_xyz'
python_name = 'example_plugin.some_module:get_reader'
title = 'Read ".xyz" files'

id = 'example-plugin.write_points'
python_name = 'example_plugin.some_module:write_points'
title = 'Save points layer to csv'

id = 'example-plugin.my_widget'
python_name = 'example_plugin.some_module:MyWidget'
title = 'Open my widget'

id = 'example-plugin.do_threshold'
python_name = 'example_plugin.some_module:threshold'
title = 'Perform threshold on image, return new image'

id = 'example-plugin.threshold_widget'
python_name = 'example_plugin.some_module:widget_factory'
title = 'Make threshold widget with magic_factory'

id = ''
python_name = 'example_plugin.some_module:create_fractal'
title = 'Create fractal image'

accepts_directories = false
command = 'example-plugin.read_xyz'
filename_patterns = [ '*.xyz' ]

command = ''
display_name = 'Fractal'
key = 'fractal'

display_name = 'Tabueran Kiribati'
key = 'napari'
uri = ''

id = 'monokai'
label = 'Monokai'
type = 'dark'

    background = '#272822'
    canvas = 'black'
    console = 'black'
    current = '#66d9ef'
    foreground = '#75715e'
    highlight = '#e6db74'
    primary = '#cfcfc2'
    secondary = '#f8f8f2'
    text = '#a1ef34'
    warning = '#f92672'

command = 'example-plugin.my_widget'
display_name = 'Wizard'

command = 'example-plugin.threshold_widget'
display_name = 'Threshold'

autogenerate = true
command = 'example-plugin.do_threshold'
display_name = 'Threshold'

command = 'example-plugin.write_points'
filename_extensions = [ '.csv' ]
layer_types = [ 'points' ]