Show HN: New Python GUI Framework (better than others?)

A ridiculously Pythonic and powerful framework for building beautiful desktop applications.

WinUp is a modern UI framework for Python that wraps the power of PySide6 (Qt) in a simple, declarative, and developer-friendly API. It's designed to let you build applications faster, write cleaner code, and enjoy the development process.

Desktop development in Python can feel clunky. WinUp was built to fix that.

In short, WinUp provides the "killer features" of modern web frameworks (like React or Vue) for the desktop, saving you time and letting you focus on what matters: your application's logic.

✅ = Built-in or robust
⚠️ = Partial or limited
❌ = Missing entirely

• Declarative & Pythonic UI: Build complex layouts with simple Row and Column objects instead of clunky box layouts.
• Component-Based Architecture: Use the @component decorator to create modular and reusable UI widgets from simple functions.
• Powerful Styling System: Style your widgets with simple Python dictionaries using props. Create global "CSS-like" classes with style.add_style_dict.
• Full Application Shell: Build professional applications with a declarative API for MenuBar, ToolBar, StatusBar, and SystemTrayIcon.
• Asynchronous Task Runner: Run long-running operations in the background without freezing your UI using the simple @tasks.run decorator.
• Performance by Default: Includes an opt-in @memo decorator to cache component renders and prevent needless re-computation.
• Advanced Extensibility:
  • Widget Factory: Replace any default widget with your own custom implementation (e.g., C++ based) using ui.register_widget().
  • Multiple Windows: Create and manage multiple independent windows for complex applications like tool palettes or music players.
• Reactive State Management:
  • One-Way Binding: Automatically update your UI when your data changes with state.bind().
  • Two-Way Binding: Effortlessly sync input widgets with your state using state.bind_two_way().
  • Subscriptions: Trigger any function in response to state changes with state.subscribe().
• Developer-Friendly Tooling:
  • Hot Reloading: See your UI changes instantly without restarting your app.
  • Profiler: Easily measure the performance of any function with the @profiler.measure() decorator.
  • Window Tools: Center, flash, or manage your application window with ease.
• Built-in Routing: Easily create multi-page applications with an intuitive, state-driven router.
• Flexible Data Layer: Includes simple, consistent connectors for SQLite, PostgreSQL, MySQL, MongoDB, and Firebase.

The watchdog library is required for the Hot Reloading feature.

This makes an app template ready for use, if LoadUp doesn't work, use PyInstaller instead.

Creating an application is as simple as defining a main component and running it.

WinUp abstracts away Qt's manual layout system. You build UIs by composing Row and Column components.

Beyond simple Row and Column, WinUp provides more advanced layouts for building complex UIs.

1. Stack Layout

A Stack layout places its children on top of each other, like a deck of cards. Only one child is visible at a time. This is perfect for wizards, tab-less interfaces, or navigation with a RouterView.

2. Grid Layout

For form fields, dashboards, or calculator-style interfaces, the Grid layout is ideal. You specify children as tuples containing the widget and its grid position: (widget, row, col). You can also specify row and column spans: (widget, row, col, row_span, col_span).

3. Row & Column Stretching (Flexbox-like)

To create flexible UIs that adapt to window size, you can add a stretch factor to children of a Row or Column. This works like the flex-grow property in CSS. A child with a higher stretch factor will take up more available space.

In this example, the middle label (stretch: 2) will be twice as wide as the other two.

You can style any widget by passing a props dictionary. Props can be CSS-like properties, or special keywords like class and id for use with a global stylesheet.

WinUp includes a powerful theming system that lets you define and switch between different looks for your application (e.g., light and dark mode) at runtime.

The system is built on a simple concept: theme variables. You define your application's stylesheet using variables (like $primary-color or $text-color). Then, you can define multiple "themes" that provide concrete values for these variables.

1. Using Theme Variables

You can use theme variables in two places:

• In a global stylesheet using style.styler.add_style_dict().
• Directly in a widget's props dictionary.

2. Switching Themes

WinUp comes with built-in light and dark themes. You can switch between them at any time using style.styler.themes.set_theme().

3. Creating Custom Themes

You can easily define your own themes by providing a dictionary of variable names to color values.

While you can use raw ui elements everywhere, the best way to build a maintainable application is to create your own library of reusable components. WinUp provides two main ways to do this.

1. Styled Variants (Recommended)

This is the most common and powerful pattern. You can create a new, reusable component by wrapping a base widget with default props. This is perfect for creating a consistent design system (e.g., PrimaryButton, SecondaryButton, Card, Avatar).

The ui.create_component function is the key to this pattern.

2. Subclassing (For Advanced Behavior)

If you need to add new behavior to a widget (not just styles), you can fall back to standard Python subclassing. This is useful for creating highly specialized components with their own internal logic. After creating your class, you can register it with ui.register_widget to make it available everywhere.

While subclassing is great for creating new kinds of widgets, sometimes you just want to add a small, reusable piece of behavior to an existing widget—like making it draggable or giving it a right-click menu. This is where Traits come in.

Traits are modular behaviors that can be dynamically attached to any widget instance. WinUp comes with several built-in traits:

• draggable & droptarget: A powerful, data-driven system for drag-and-drop functionality.
• context_menu: Adds a custom right-click context menu.
• tooltip: A simple way to add a hover tooltip.
• hover_effect: Applies a [hover="true"] style property on mouse-over, which you can target in your stylesheets (e.g., QPushButton[hover="true"]).
• highlightable: Makes the text of a widget (like ui.Label) selectable by the user.

You can add a trait to any widget using winup.traits.add_trait().

Example: Advanced Drag-and-Drop

The new drag-and-drop system is data-driven. You make a widget draggable and provide it with data. You make another widget a droptarget and tell it what kind of data it accepts and what to do on_drop.

WinUp includes a powerful state management system that lets you create reactive UIs with minimal boilerplate. The new, recommended approach is object-oriented, making your code safer and more readable.

The New Way: state.create() and bind_to() (Recommended)

Instead of using string keys, you now create dedicated State objects. These objects are the single source of truth for your data and provide methods to interact with that data.

The real power comes from the bind_to() method, which can link one or more state objects to any widget property, using a simple function to format the final value.

1. Simple Counter Example

Here, we create a counter state object and bind it to a label's text property. The lambda function formats the output.

2. Multi-State Binding

Need a widget to react to changes in multiple state values? Use the and_() method to combine them. The formatter lambda will receive the state values as arguments in the same order.

3. Two-Way Binding for Inputs

For the common case of syncing an Input widget with a state, the bind_two_way() helper is still available. It works directly with the state key.

Legacy State Management (Old API)

For backward compatibility, the older, string-based API is still functional.

• winup.state.set("key", value): Sets a value in the global store.
• winup.state.get("key"): Retrieves a value.
• winup.state.bind(widget, "property", "key"): A simple one-way binding to a widget's property.
• winup.state.subscribe("key", callback): Calls a function whenever a value changes.

To keep your application responsive, any long-running operation (like a network request or a complex calculation) should be run on a background thread. WinUp makes this incredibly simple with the @tasks.run decorator.

It handles all the complex threading logic for you. You just need to provide callbacks for when the task starts, finishes, or encounters an error.

The decorator accepts three optional callback arguments:

• on_start: A function to call right before the task begins executing.
• on_finish: A function that will receive the return value of your function if it completes successfully.
• on_error: A function that will receive a (exception, traceback) tuple if your function raises an exception.

Hot Reloading (React-style Fast Refresh): WinUp now features a fully automatic, intelligent hot reloading system. Simply run your application with dev=True, and the framework will automatically watch all of your project's Python files for changes.

When you save a file, WinUp will instantly reload the relevant parts of your code and re-render your UI without restarting the entire application, preserving your application's state. This provides a seamless development experience similar to modern web frameworks.

How to Use: Just pass the dev=True flag to the run function. That's it!

This setup allows you to see UI changes instantly just by saving any file in your project.

Performance & Memoization: For UIs that render large amounts of data, you can significantly improve performance by caching component results. The @winup.memo decorator automatically caches the widget created by a component. If the component is called again with the same arguments, the cached widget is returned instantly instead of being re-created.

Profiler: Simply add the @profiler.measure() decorator to any function to measure its execution time. Results are printed to the console when the application closes. The profiler also automatically tracks the performance of the memoization cache, showing you hits, misses, and the overall hit ratio.

WinUp includes a simple yet powerful router that allows you to build applications with multiple pages or views, like a settings screen, a user dashboard, or different application tabs.

The system is built around three core concepts:

1. Router: An object that holds your application's routes (a mapping of a path like "/home" to a component function) and manages the current state.
2. RouterView: A special component that acts as a placeholder. It automatically displays the correct component for the current route.
3. RouterLink: A clickable component (like a hyperlink) that tells the Router to navigate to a different path.

Example: A Simple Multi-Page App

Here's how you can structure a basic application with a "Home" and "Settings" page.

To manage side effects—like fetching data, setting up timers, or starting animations—WinUp components now have lifecycle hooks. These are special functions you can pass to a component that run at specific times.

• on_mount: This function is called exactly once, right after the component's UI has been created and added to the scene (i.e., it has "mounted"). It's the perfect place to load data or start animations.
• on_unmount: This function is called exactly once, just before the component is destroyed and removed from the scene. It's essential for cleanup tasks, like canceling network requests, invalidating timers, or saving state.

Example: A Self-Updating Clock

This example demonstrates how to use on_mount to start a timer and on_unmount to clean it up, preventing memory leaks.

WinUp provides a simple API for creating smooth animations, located in the winup.animate.fx module. You can easily fade widgets in and out or animate any of their properties.

Example: Fading and Moving

This example shows how to use fade_in, fade_out, and the generic animate function to move a widget.

WinUp includes a powerful hot-reloading feature to accelerate development. When enabled, any changes you make to your component files will be reflected instantly in your running application without needing a manual restart.

The hot-reloading service monitors your project's Python files. When a change is detected, it intelligently reloads the necessary modules and redraws the UI, preserving the application's state. This is ideal for iterating quickly on UI design and component logic.

To enable hot reloading, you must run your application in development mode. This is done by passing dev=True to the winup.run() function.

You also need to provide the main component as a string path in the format "path.to.module:ComponentName". This allows WinUp to dynamically re-import your component when the source file changes.

Here is how you would structure your main application script to use hot reloading:

Now, when you run python main.py, any changes you make to my_app/my_component.py (or any other component file) will be reflected instantly.

WinUp is an open-source project. Contributions are welcome!

This project is licensed under the Apache 2.0 License.