Module Attributes



alias of function


A class to encapsulate hook implementations.


Core class which manages registration of plugin objects and hook calls.



Trigger discovery of dock_widgets plugins

napari.plugins.get_plugin_widget(plugin_name, widget_name=None)[source]

Get widget widget_name provided by plugin plugin_name.

Note: it’s important that discover_dock_widgets() has been called first, otherwise plugins may not be found yet. (Typically, that is done in qt_main_window)

  • plugin_name (str) – Name of a plugin providing a widget

  • widget_name (str, optional) – Name of a widget provided by plugin_name. If None, and the specified plugin provides only a single widget, that widget will be returned, otherwise a ValueError will be raised, by default None


plugin_widget – Tuple of (widget_class, options).

Return type

Tuple[Callable, dict]

  • KeyError – If plugin plugin_name does not provide any widgets

  • KeyError – If plugin does not provide a widget named widget_name.

  • ValueError – If widget_name is not provided, but plugin_name provides more than one widget

napari.plugins.magicgui(function=None, *, layout='vertical', labels=True, tooltips=True, call_button=None, auto_call=False, result_widget=False, main_window=False, app=None, persist=False, **param_options)[source]

Return a FunctionGui for function.

  • function (Callable, optional) – The function to decorate. Optional to allow bare decorator with optional arguments. by default None

  • layout (str, optional) – The type of layout to use. Must be one of {‘horizontal’, ‘vertical’}. by default “vertical”.

  • labels (bool, optional) – Whether labels are shown in the widget. by default True

  • tooltips (bool, optional) – Whether tooltips are shown when hovering over widgets. by default True

  • call_button (bool or str, optional) – If True, create an additional button that calls the original function when clicked. If a str, set the button text. If None (the default), it defaults to True when auto_call is False, and False otherwise.

  • auto_call (bool, optional) – If True, changing any parameter in either the GUI or the widget attributes will call the original function with the current settings. by default False

  • result_widget (bool, optional) – Whether to display a LineEdit widget the output of the function when called, by default False

  • main_window (bool) – Whether this widget should be treated as the main app window, with menu bar, by default False.

  • app (magicgui.Application or str, optional) – A backend to use, by default None (use the default backend.)

  • persist (bool, optional) – If True, when parameter values change in the widget, they will be stored to disk and restored when the widget is loaded again with persist = True. Call magicgui._util.user_cache_dir() to get the default cache location. By default False.

  • **param_options (dict of dict) – Any additional keyword arguments will be used as parameter-specific options. Keywords MUST match the name of one of the arguments in the function signature, and the value MUST be a dict.


result – If function is not None (such as when this is used as a bare decorator), returns a FunctionGui instance, which is a list-like container of autogenerated widgets corresponding to each parameter in the function. If function is None such as when arguments are provided like magicgui(auto_call=True), then returns a function that can be used as a decorator.

Return type

FunctionGui or Callable[[F], FunctionGui]


>>> @magicgui
... def my_function(a: int = 1, b: str = 'hello'):
...     pass
>>> my_function.a.value == 1  # True
>>> my_function.b.value = 'world'
napari.plugins.register_dock_widget(args, hookimpl)[source]
napari.plugins.register_function_widget(args, hookimpl)[source]

Infer whether we are running as a briefcase bundle

Return type


napari.plugins.signature(obj, *, follow_wrapped=True)[source]

Get a signature object for the passed callable.


Platform-specific location of site-packages folder in user library

Return type


napari.plugins.warn(message, category=None, stacklevel=1, source=None)

Issue a warning, or maybe ignore it or raise an exception.