{"id":9914,"library":"magicgui","title":"MagicGUI","description":"magicgui is a Python library that automatically generates graphical user interfaces (GUIs) from functions, primarily leveraging type hints for widget inference. It aims to make GUI creation simple and declarative, supporting various GUI backends (like Qt, wxPython, GTK, or custom) via `qtpy` and `app-model`. The current stable version is 0.10.2, with active development and frequent releases.","status":"active","version":"0.10.2","language":"en","source_language":"en","source_url":"https://github.com/napari/magicgui","tags":["GUI","declarative","widgets","type-hints","qt","pyside","pyqt","app-model"],"install":[{"cmd":"pip install magicgui","lang":"bash","label":"Basic installation"},{"cmd":"pip install magicgui[qt]","lang":"bash","label":"Installation with Qt backend (recommended)"}],"dependencies":[{"reason":"Required for the most common Qt backend to run magicgui applications. While optional, it's often needed in practice.","package":"qtpy","optional":true},{"reason":"Core dependency for the underlying model system, automatically installed.","package":"app-model","optional":false}],"imports":[{"symbol":"magicgui","correct":"from magicgui import magicgui"},{"symbol":"Container","correct":"from magicgui.widgets import Container"},{"note":"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.","wrong":"from magicgui.widgets import FunctionGui","symbol":"FunctionGui (direct instantiation)","correct":"from magicgui.function_gui import FunctionGui"}],"quickstart":{"code":"import os\nimport sys\nfrom magicgui import magicgui\nfrom magicgui.widgets import Container\n\n# Ensure a Qt application is running for the GUI to display\ntry:\n    from qtpy.QtWidgets import QApplication\n    app = QApplication.instance() # Use existing app if any\n    if app is None:\n        app = QApplication(sys.argv)\nexcept ImportError:\n    print(\"Install `pip install magicgui[qt]` for a complete experience.\")\n    sys.exit(1)\n\n@magicgui(auto_call=True, layout=\"horizontal\", result_widget=True)\ndef calculate_sum(a: int = 1, b: int = 2) -> int:\n    \"\"\"Calculates the sum of two numbers.\"\"\"\n    return a + b\n\n@magicgui(call_button=\"Display Message\")\ndef show_message(text: str = \"Hello, magicgui!\"):\n    \"\"\"Displays a message in the console.\"\"\"\n    print(f\"User message: {text}\")\n\n# Create a container to hold multiple magicgui functions\nmain_container = Container(widgets=[calculate_sum, show_message], labels=False)\nmain_container.show()\n\n# Start the Qt event loop if running as a standalone script\nif app is not None and app.exec_ is not None:\n    sys.exit(app.exec_())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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...`.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.8.0 to 0.8.0+"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `magicgui` with the `qt` extra: `pip install magicgui[qt]` or manually install `qtpy` and a specific binding: `pip install qtpy pyqt6`.","cause":"magicgui could not find any installed Qt binding (PyQt5, PySide2, PyQt6, PySide6) or `qtpy` (which abstracts them).","error":"RuntimeError: No Qt backend found, please install qtpy and a Qt binding."},{"fix":"Replace calls to `function_gui_instance.show_dialog()` with `function_gui_instance.show()`.","cause":"The `show_dialog` method was deprecated and removed in favor of `show()` in recent versions of magicgui (0.8.0+).","error":"AttributeError: 'FunctionGui' object has no attribute 'show_dialog'"},{"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.","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.","error":"TypeError: magicgui arguments must be hashable and bound to a function... (or similar TypeError related to decorator arguments)"},{"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_())`.","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.","error":"My magicgui window appears but immediately closes / is unresponsive."}]}