Manifest Reference#

Important

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
[options.entry_points]
napari.manifest =
    example-plugin = example_plugin:napari.yaml

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

Fields#

All fields are optional except those in bold.

Name

Details

name

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

display_name

User-facing text to display as the name of this plugin. Must be 3-90 characters long 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.

visibility

Whether this plugin should be searchable and visible in the built-in plugin installer and the napari hub. By default ('public') all plugins are visible. To prevent your plugin from appearing in search results, change this to 'hidden'.

icon

The path to a square PNG icon of at least 128x128 pixels (256x256 for Retina screens). May be one of:

  • a secure (https) URL
  • a path relative to the manifest file, (must be shipped in the sdist)
  • a string in the format {package}:{resource}, where package and resource are arguments to importlib.resources.path(package, resource), (e.g. top_module.some_folder:my_logo.png).

categories

A list of categories that this plugin belongs to. This is used to help users discover your plugin. Allowed values: [Acquisition, Annotation, Dataset, Image Processing, IO, Measurement, Segmentation, Simulation, Themes, Transformations, Utilities, Visualization]

schema_version

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

on_activate

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).

on_deactivate

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.

contributions

An object describing the plugin’s contributions

Note

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

Example#

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).

Tip

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.2.0
contributions:
  commands:
  - 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: example-plugin.data.fractal
    title: Create fractal image
    python_name: example_plugin.some_module:create_fractal
  readers:
  - command: example-plugin.read_xyz
    filename_patterns:
    - '*.xyz'
    accepts_directories: false
  writers:
  - command: example-plugin.write_points
    layer_types:
    - points
    filename_extensions:
    - .csv
  widgets:
  - 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
  sample_data:
  - command: example-plugin.data.fractal
    key: fractal
    display_name: Fractal
  - key: napari
    display_name: Tabueran Kiribati
    uri: https://en.wikipedia.org/wiki/Napari#/media/File:Tabuaeran_Kiribati.jpg
  themes:
  - id: monokai
    label: Monokai
    type: dark
    syntax_style: monokai
    colors:
      canvas: black
      console: black
      background: '#272822'
      foreground: '#75715e'
      primary: '#cfcfc2'
      secondary: '#f8f8f2'
      highlight: '#e6db74'
      text: '#a1ef34'
      icon: '#a1ef34'
      warning: '#f92672'
      current: '#66d9ef'

name = "example-plugin"
display_name = "Example Plugin"
schema_version = "0.2.0"

[contributions]
widgets = [
    { 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 },
]

[[contributions.commands]]
id = "example-plugin.hello_world"
title = "Hello World"

[[contributions.commands]]
id = "example-plugin.read_xyz"
title = "Read \".xyz\" files"
python_name = "example_plugin.some_module:get_reader"

[[contributions.commands]]
id = "example-plugin.write_points"
title = "Save points layer to csv"
python_name = "example_plugin.some_module:write_points"

[[contributions.commands]]
id = "example-plugin.my_widget"
title = "Open my widget"
python_name = "example_plugin.some_module:MyWidget"

[[contributions.commands]]
id = "example-plugin.do_threshold"
title = "Perform threshold on image, return new image"
python_name = "example_plugin.some_module:threshold"

[[contributions.commands]]
id = "example-plugin.threshold_widget"
title = "Make threshold widget with magic_factory"
python_name = "example_plugin.some_module:widget_factory"

[[contributions.commands]]
id = "example-plugin.data.fractal"
title = "Create fractal image"
python_name = "example_plugin.some_module:create_fractal"

[[contributions.readers]]
command = "example-plugin.read_xyz"
filename_patterns = [
    "*.xyz",
]
accepts_directories = false

[[contributions.writers]]
command = "example-plugin.write_points"
layer_types = [
    "points",
]
filename_extensions = [
    ".csv",
]

[[contributions.sample_data]]
command = "example-plugin.data.fractal"
key = "fractal"
display_name = "Fractal"

[[contributions.sample_data]]
key = "napari"
display_name = "Tabueran Kiribati"
uri = "https://en.wikipedia.org/wiki/Napari#/media/File:Tabuaeran_Kiribati.jpg"

[[contributions.themes]]
id = "monokai"
label = "Monokai"
type = "dark"
syntax_style = "monokai"

[contributions.themes.colors]
canvas = "black"
console = "black"
background = "#272822"
foreground = "#75715e"
primary = "#cfcfc2"
secondary = "#f8f8f2"
highlight = "#e6db74"
text = "#a1ef34"
icon = "#a1ef34"
warning = "#f92672"
current = "#66d9ef"
On this page