MagicGUI

Common errors

• RuntimeError: No Qt backend found, please install qtpy and a Qt binding.

  cause magicgui could not find any installed Qt binding (PyQt5, PySide2, PyQt6, PySide6) or `qtpy` (which abstracts them).
  fix Install `magicgui` with the `qt` extra: `pip install magicgui[qt]` or manually install `qtpy` and a specific binding: `pip install qtpy pyqt6`.

• AttributeError: 'FunctionGui' object has no attribute 'show_dialog'

  cause The `show_dialog` method was deprecated and removed in favor of `show()` in recent versions of magicgui (0.8.0+).
  fix Replace calls to `function_gui_instance.show_dialog()` with `function_gui_instance.show()`.

• TypeError: magicgui arguments must be hashable and bound to a function... (or similar TypeError related to decorator arguments)

  cause This often occurs when arguments passed to the `@magicgui` decorator are incorrect, or when attempting to use the decorator on a method without proper binding or `self` handling.
  fix Ensure all arguments passed to `@magicgui(...)` are valid keyword arguments as per the decorator's API. If decorating a method, consider using `bound=True` if you're not explicitly passing the `self` instance when calling the function. Review the `magicgui` decorator signature in the documentation.

• My magicgui window appears but immediately closes / is unresponsive.

  cause The GUI event loop (e.g., QApplication.exec_() for Qt) is not running or not properly engaged to keep the window alive and interactive.
  fix For standalone scripts, make sure you explicitly start the event loop after creating and showing your magicgui window(s). For example, `app = QApplication(sys.argv); my_gui.show(); sys.exit(app.exec_())`.

Warnings

• gotcha magicgui requires a GUI backend (like Qt/PyQt/PySide) and `qtpy` to function. Without at least one installed, you'll encounter a `RuntimeError: No Qt backend found...`.
  Fix: Install `pip install magicgui[qt]` which includes `qtpy` and a suitable Qt binding (e.g., PySide6/PyQt6), or manually install `qtpy` and your preferred Qt binding (e.g., `pip install qtpy pyqt6`). Ensure a `QApplication` (or equivalent for other backends) is instantiated and running.
• gotcha magicgui relies heavily on Python type hints to infer appropriate widgets. Missing, incorrect, or ambiguous type hints will result in default widgets (e.g., `QLineEdit` for strings without an explicit annotation for `str` type), or unexpected UI behavior.
  Fix: Always use explicit, correct type hints for function arguments and return values. Refer to the magicgui documentation for supported types and how they map to specific widgets (e.g., `int` -> `SpinBox`, `bool` -> `CheckBox`, `Enum` -> `ComboBox`).
• gotcha If your magicgui window appears and immediately closes, or is unresponsive, it's likely that the GUI event loop for your chosen backend (e.g., `QApplication.exec_()` for Qt) is not running or not properly integrated.
  Fix: For standalone scripts, ensure you explicitly start the event loop after showing your window (e.g., `app = QApplication([]); container.show(); app.exec_()`). When embedding in an existing application, ensure magicgui components are added to an already running event loop.
• breaking Significant API changes occurred in versions >= 0.8.0, particularly around `app-model` integration. The `bind` decorator for argument injection was removed, `show_dialog` was deprecated, and direct `FunctionGui` instantiation from `magicgui.widgets` became less common/recommended.
  Fix: Update code to use the `@magicgui` decorator for creating `FunctionGui` objects. Replace `bind` with new patterns for argument injection (see `FunctionGui.inject`). Migrate from `show_dialog` to `FunctionGui.show()`. Refer to the official migration guides for versions 0.8.0 and beyond.

Install

• pip install magicgui Basic installation
• pip install magicgui[qt] Installation with Qt backend (recommended)

Imports

• magicgui

  from magicgui import magicgui

• Container

  from magicgui.widgets import Container

• FunctionGui (direct instantiation)
  wrong:

  from magicgui.widgets import FunctionGui

  correct:

  from magicgui.function_gui import FunctionGui

  While `magicgui.widgets.FunctionGui` used to be directly imported for instantiation, the recommended approach since 0.8.0 is to use the `@magicgui` decorator, or instantiate `magicgui.function_gui.FunctionGui` directly if decorator is not suitable.

Quickstart

This quickstart demonstrates how to create two simple GUI elements using the `@magicgui` decorator: one for calculation and another for message display. It then combines them into a `Container` and shows the window. It also includes the necessary `QApplication` setup to make the GUI runnable as a standalone script, which is a common requirement.

import os
import sys
from magicgui import magicgui
from magicgui.widgets import Container

# Ensure a Qt application is running for the GUI to display
try:
    from qtpy.QtWidgets import QApplication
    app = QApplication.instance() # Use existing app if any
    if app is None:
        app = QApplication(sys.argv)
except ImportError:
    print("Install `pip install magicgui[qt]` for a complete experience.")
    sys.exit(1)

@magicgui(auto_call=True, layout="horizontal", result_widget=True)
def calculate_sum(a: int = 1, b: int = 2) -> int:
    """Calculates the sum of two numbers."""
    return a + b

@magicgui(call_button="Display Message")
def show_message(text: str = "Hello, magicgui!"):
    """Displays a message in the console."""
    print(f"User message: {text}")

# Create a container to hold multiple magicgui functions
main_container = Container(widgets=[calculate_sum, show_message], labels=False)
main_container.show()

# Start the Qt event loop if running as a standalone script
if app is not None and app.exec_ is not None:
    sys.exit(app.exec_())