The @magicgui decorator is one of the main exports from magicgui. It inspects the signature of a callable object, and selects a widget type appropriate for each parameter in the signature. It then returns a GUI (a FunctionGui instance to be precise) wrapping all of the widgets. It can be used to quickly generate an interactive graphical component that can control and call the decorated function or method.

@magicgui.magicgui(function=None, *, layout='vertical', scrollable=False, 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”.

  • scrollable (bool, optional) – Whether to enable scroll bars or not. If enabled, scroll bars will only appear along the layout direction, not in both directions.

  • 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'