Install & Compatibility
Where this runs
tested against v0.10.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.259s · 37.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.236s · 38MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
magicgui
✓ from magicgui import magicgui
Container
✓ from magicgui.widgets import Container
FunctionGui (direct instantiation)
✓ from magicgui.function_gui import FunctionGui
✗ from magicgui.widgets 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.
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_())
Debug
Known issues
gotchamagicgui 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...`.fixInstall `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.
affects: All versions
gotchamagicgui 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.fixAlways 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`).
affects: All versions
gotchaIf 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.fixFor 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.
affects: All versions
breakingSignificant 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.fixUpdate 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.
affects: <0.8.0 to 0.8.0+
Errors
Common errors & fixes
RuntimeError: No Qt backend found, please install qtpy and a Qt binding.
magicgui could not find any installed Qt binding (PyQt5, PySide2, PyQt6, PySide6) or `qtpy` (which abstracts them).
fixInstall `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'
The `show_dialog` method was deprecated and removed in favor of `show()` in recent versions of magicgui (0.8.0+).
fixReplace 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)
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.
fixEnsure 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.
The GUI event loop (e.g., QApplication.exec_() for Qt) is not running or not properly engaged to keep the window alive and interactive.
fixFor 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_())`.
Upgrade
Version history
0.10.2latest on PyPI · released Apr 10, 2026
Audit
Dependencies
qtpyoptionalRequired for the most common Qt backend to run magicgui applications. While optional, it's often needed in practice.
app-modelrequiredCore dependency for the underlying model system, automatically installed.