pygubu-designer: laying out tkinter interfaces visually

Drag a window together, save it as an XML .ui file

pygubu-designer is a RAD tool, in the sense the project means it: a rapid application development environment for tkinter, where the point is to reach a working user interface quickly without hand-placing every widget. The description calls it a simple GUI designer for the Python tkinter module, and the README states the intent as quick and easy development of user interfaces for tkinter.

The output is an XML file with the.ui extension. That file is loaded dynamically by applications through the pygubu builder, which is the separate runtime piece this project depends on. The design is explicitly modelled on Glade, and the README names it as the inspiration, which tells you the mental model to expect: one declarative document describing the interface that the application reads at startup.

The audience is a Python developer who already knows what a tkinter widget is. The gain is in layout and event wiring, not in learning the toolkit. The examples directory makes that concrete, with folders for dialogs, forms, canvas work, menus, image properties, a gettext internationalisation demo, and packaging integrations for cx_Freeze, Nuitka, py2exe, PyInstaller, zipapp and tkcalendar.

Two workflows, and the second one removes the .ui file

The same class-based structure runs through both workflows, and the difference is where the interface lives. In the classic method, the application uses the .ui file and pygubu creates the widgets and connects the defined bindings at runtime. The README recommends this mode for applications with one or a few windows, while noting it works for apps of any complexity. Pygubu Designer itself was originally built this way and now uses the other mode.

In the second method, the designer generates the Python code for the base class and you write the application logic in the derived class. The .ui file is then not needed at runtime, the app can become pure tkinter if you avoid pygubu widgets, which removes the pygubu dependency at runtime, and custom widgets become easier to create.

Those trade-offs are worth being precise about. The classic mode gives you a single editable document that the designer can reopen and modify, and the code generation mode gives you a frozen artifact you can diff, review and ship. Whichever you pick, the interface can still be modified later in the designer, which is the property that makes either choice recoverable rather than a one-way door.

The examples folder shows both in practice. examples/button_cb.ui sits next to examples/button_cb.py for a callback on a button, and examples/managers.ui covers the geometry managers, with examples/commands.py, examples/control_variables/ and examples/custom_widget/ showing the other patterns.

Installing from PyPI and starting the designer on Unix-like systems

The current package requires Python 3.9 or newer. Installing it is a single pip command, and the project publishes a console entry point named pygubu-designer, wired in pyproject.toml to the callable pygubudesigner.main:start_pygubu under the gui-scripts group, so no console window appears on platforms that support it.

pip install pygubu-designer

On Unix-like systems you start the designer by typing the command name in a terminal:

pygubu-designer

For other platforms the README points to a wiki page called Launch, and for installation methods other than pip it points to a wiki page titled Installation & Related. That is where Windows-specific instructions live, since the terminal invocation documented here is explicitly for Unix-like systems.

A first session is straightforward. You open or create a .ui file, drop widgets onto the canvas, set their properties, wire callbacks in the handlers table, save the file, and then load it from your application with the pygubu builder. If you prefer the second workflow, you use the code generation step instead and keep only the generated base class in your project.

The dependency list tells you how the code generation works

pyproject.toml pins the runtime requirements and they explain the machinery. The package depends on pygubu >= 0.42, which is the builder that reads the.ui file at runtime, and on Mako >= 1.1.4, a template engine, which is the natural implementation for rendering a base class from a template plus the widget tree. screeninfo >= 0.8 handles display geometry, platformdirs >= 4.4.0 handles per-platform directories, autopep8 >= 1.7 suggests generated Python is formatted automatically. backports.strenum is pulled in only on Python versions below 3.11.

The version is 0.46.2, and the classifiers list Python 3.9 through 3.14 with the Development Status:: 4 - Beta marker and an OS Independent operating system tag. The project is packaged with setuptools through setup.py and pyproject.toml, and a.pre-commit-config.yaml plus a tests/ directory sit in the repository root, with a development/ directory for local work and a run.sh convenience script.

The absence of a hard tkinter dependency is notable. Python's standard library includes the tkinter module, so the tool relies on the tkinter and Tk setup of the user's Python installation rather than bundling it.

Third-party widget packs are optional extras, not requirements

The optional-dependencies table is the part of pyproject.toml that shows how far the designer can be stretched. Separate extras exist for ttkwidgets, tksheet, tkinterweb, tkintertable, tkcalendar, AwesomeTkinter, tkintermapview, and customtkinter, which is pinned at 5.2.2 or newer and pulls in packaging and pillow. An all extra is defined as well, collecting the set.

This is a sensible design choice for a GUI designer, because the third-party widget landscape changes fast and pinning every pack as a hard requirement would make the base install heavy and fragile. It also means the extras are opt-in per project, and a team that wants a bare tkinter application does not have to install a third-party widget ecosystem to design it.

The catch is that each extra is a promise the project does not fully own. Support for a specific pack depends on that pack's widget API staying stable, and the README explicitly warns about a narrower point along the same lines: if you use a third-party plugin, check the plugin license. The designer and its core plugins are covered, but anything you pull in from outside carries its own terms.

Where a visual designer is the wrong choice

The clearest wrong-tool case is a toolkit other than tkinter. Every artefact this project produces is either an XML file meant for the pygubu builder or generated tkinter code. A team building a Qt, GTK or web front end gets nothing from it, and the fact that the designer is inspired by Glade does not make it a Glade-compatible editor for other toolkits.

The second case is scale and governance. The documentation is a README, a wiki, an examples folder and a change list in HISTORY.md. There is no documented plugin API for extending the designer itself, no stated support policy, and no release history on GitHub, since the repository has no GitHub releases at all. For a team that needs a designer to be a stable platform dependency with a compatibility promise, a tool whose releases live in a changelog file is a harder sell, however capable the layout canvas is.

Third, for a one-window script, the designer is overhead. Writing a few pack and grid calls is faster than modelling the same window in a canvas, saving it, and loading it through a builder at startup.

Beta status, a GPL designer, and MIT generated scripts

The repository is not archived, and the last push was on 2026-10-14, so the project is being worked on now. The version in pyproject.toml is 0.46.2, the status classifier calls it Beta, and the release history is tracked in HISTORY.md rather than in GitHub releases. There is no versioned artifact to pin in a requirements file beyond the PyPI version, so an upgrade means checking HISTORY.md for what changed and then reinstalling.

The licence story has two layers, and the README is explicit about it. Pygubu Designer itself is GPL-3.0, and the LICENSE.md file sits in the repository root. But the Python code the designer generates is licensed under the MIT License, the same licence as the pygubu core, and this applies to the standard plugins that come with pygubu core. If you use a third-party plugin, the README says to check that plugin's own licence.

That split has a direct consequence. A generated base class in your own project carries MIT terms, so you are not obliged to release your application under GPL because you used the designer. The tool you run to design it is GPL. This is not legal advice, but it is the distinction to verify before shipping a commercial product that used Pygubu Designer in the design phase.

Editorial conclusion

Adopt pygubu-designer if you build tkinter applications and want to lay out windows visually instead of hand-writing grid and pack calls, and pick the generated-code mode when you need a build with no .ui file at runtime. Do not adopt it for a toolkit other than tkinter, for a large team that needs a designer with a documented extension API, or for anything that needs production polish, since the project is classified as Beta and keeps its change log in HISTORY.md. Before committing, open the Installation & Related wiki page to see the non-pip options, and read the licence section in the README, because the designer itself is GPL-3.0 while the Python code it generates is MIT.

Frequently asked questions

Official sources

1. alejandroautalan/pygubu-designer on GitHub
2. Issues
3. License: GPL-3.0
4. README