# Gooey: turning a Python argparse script into a GUI with one decorator

> Gooey wraps an existing argparse program in a wxPython desktop interface, mapping each parser action to a widget. It suits small office scripts aimed at non-programmers, not pipes and batch jobs.

**chriskiehl/Gooey** — Turn (almost) any Python command line program into a full GUI application with one line

- Repository: https://github.com/chriskiehl/Gooey
- Stars: 21,911 · Forks: 1,041
- Language: Python
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/chriskiehl-gooey

## What Gooey actually converts, and who it converts it for

Gooey takes a Python 3 program that already declares its options with argparse and renders those options as a desktop form. The README states the goal plainly: "Turn (almost) any Python 3 Console Program into a GUI application with one line." The one line is a decorator, and the program underneath keeps using argparse for parsing.

The intended audience is narrow and the README says so. If you are building utilities for yourself, for other programmers, or something whose output you want to capture and pipe into another console application, the README states that Gooey probably is not the tool for you. The fit is "run and done" scripts around an office: things that move bits from point A to point B, or anything aimed at a non-programmer. That distinction matters more than any feature list. A tool that produces stdout for a shell pipeline loses value when it is wrapped in a window, and Gooey does not try to be that tool.

So the problem it solves is not argument parsing. argparse already does that well. The problem is that supplying arguments to a console program requires explaining flags to someone who does not want to learn them, and the alternative has always been building a GUI by hand. Gooey removes that second job for scripts that fit its shape.

## How the decorator becomes a window: parsing the script, mapping actions to widgets

The mechanism is unusual enough to be worth stating precisely. At run time, Gooey parses your Python script for all references to ArgumentParser. Those references are extracted, assigned a component type based on the action they provide, and used to assemble the GUI. The older optparse is not supported. This is source inspection rather than a hook into the parser object, which is why the decorator can sit on the function that contains the declarations and still know what to draw.

The mapping is documented as a table of argparse actions to wxPython components. store becomes a TextCtrl. store_const, store_true, store_False and version become CheckBoxes. append also maps to a TextCtrl. The README notes that Gooey will do its best to choose sensible widget defaults, and that finer control comes from swapping ArgumentParser for the drop-in GooeyParser. With GooeyParser you set the widget explicitly, for example widget="FileChooser" or widget="DateChooser" on an argument. That is the escape hatch when the automatic choice is wrong.

The decorator itself takes configuration: advanced toggles the advanced config screen, auto_start skips the config screens, default_size sets the starting window size, required_cols and optional_cols control the column counts in the Required and Optional sections, and dump_build_config and load_build_config write and read the JSON Gooey uses to configure itself. The README also documents run modes (Full/Advanced, Basic, and No Config), internationalization via JSON translation files, dynamic validation, lifecycle events, progress display with elapsed and remaining time, custom icons, and packaging. The dependency list in setup.py shows what the window is built on: wxpython, Pillow, psutil, colored, pygtrie, and re-wx.

## Installing Gooey and getting a first window

The README gives two installation routes. The easiest is pip. The alternative is cloning the repository and running setup.py. Both are shown below exactly as the README presents them.

```bash
pip install Gooey
```

```bash
git clone https://github.com/chriskiehl/Gooey.git
python setup.py install
```

setup.py declares python_requires='>=3.6' and pulls in wxpython>=4.1.0 along with Pillow, psutil, colored, pygtrie, re-wx, and typing-extensions==3.10.0.2. wxpython is the heavy part and the one most likely to fail on a fresh machine, so install it first if pip struggles with the combined set.

A minimal program is a function with argparse declarations and the decorator above it. The README's own example is the whole pattern:

```python
from gooey import Gooey

@Gooey
def main():
    parser = ArgumentParser(...)
    # rest of code
```

When you run that script, Gooey inspects it, finds the parser, and opens a configuration window whose fields correspond to your arguments. Pressing start runs the function. If you want a file picker instead of a text box, switch to GooeyParser and name the widget:

```python
from gooey import Gooey, GooeyParser

@Gooey
def main():
    parser = GooeyParser(description="My Cool GUI Program!")
    parser.add_argument('Filename', widget="FileChooser")
    parser.add_argument('Date', widget="DateChooser")
```

The README also points to a separate examples repository with ready-to-go scripts covering layouts, widgets, and features, which is the faster way to see the range of what the mapping produces.

## Where Gooey is the wrong tool

The README's own exclusion is the clearest limitation: utilities meant to be piped into another console application are outside the target. If your script's value is its stdout, a GUI wrapper adds a window between the user and the pipe without adding anything the shell could not do.

There are structural constraints too. optparse is not supported, so older scripts need their parsing modernized before Gooey can see anything. The extraction step depends on finding references to ArgumentParser in the script, which means dynamic parser construction, parsers built in imported modules, or arguments added in loops are not the shape this mechanism was designed around.

The dependency footprint is the practical cost. wxpython is a large native toolkit, and setup.py pins typing-extensions to an exact version, 3.10.0.2, while requirements.txt additionally pins mypy-extensions==0.4.3. Exact pins inside an application's dependency tree are a known source of resolver conflicts when the same environment holds other packages that want different versions of typing-extensions. Nothing in the repository suggests this is negotiable. On a machine where wxpython cannot be installed, Gooey cannot run at all, and there is no documented headless or browser fallback.

## Gooey against writing the GUI yourself, or shipping a web form

The real alternative is not another decorator library. It is either writing the interface directly in a toolkit such as wxPython, or exposing the same script through a small web form. The difference is where the work goes.

Hand-written wxPython gives you full control over layout, event handling and threading, at the cost of writing and maintaining all of it. Gooey trades that control for automatic generation from declarations you have already written. The trade is favourable exactly when your interface is a form of options and a run button, and unfavourable as soon as you need behaviour the mapping does not express. GooeyParser narrows that gap by letting you choose widgets, but the structure still comes from the parser.

A web form moves the problem to a browser and a server. It reaches users who cannot install a desktop application and it survives operating system differences that make wxpython installation painful. It also introduces hosting, authentication and a deployment story that a local script does not have. For an around-the-office script run on the same machine as the data, a desktop window is simpler. For anything that has to be reached by people on other machines, the web route is the one that scales, and Gooey does not compete there.

## Release cadence, pinning, and the MIT licence

The repository is not archived, and the last push was on 2026-09-12. The release history tells a more cautious story than the commit activity. The newest listed release is 1.2.0-alpha from 2022-02-04. Before it, 1.0.8.1 shipped on 2021-06-12 and 1.0.8 on 2020-12-20. setup.py carries version = '1.2.0-ALPHA', so the alpha designation is in the source itself, and the classifiers mark the project as Development Status :: 4 - Beta.

For anyone pinning a dependency, that gap matters. If you install from PyPI you will get whatever the current release is, which the repository presents as an alpha. If you want the last non-alpha line, you pin 1.0.8.1. Upgrades between those lines are not documented in the README, and no migration path is described, so treat a version bump as something to test against your own script rather than assume.

Gooey is MIT licensed, stated in setup.py and in the LICENSE.txt file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. The practical implication for a team is that Gooey can be bundled into internal or commercial tooling without a copyleft obligation. That is a statement about the licence text, not legal advice, and the transitive licences of wxpython and the other dependencies are a separate question that this repository does not answer.

## Conclusion

Adopt Gooey when you have a self-contained Python 3 script with argparse declarations and the people who run it will never open a terminal. Skip it for *nix-style utilities that produce output meant to be piped into another command, since the README places those outside its target. Before committing, check that wxpython installs cleanly on every target machine, and confirm that the release you pin is the one you intend: the newest listed release is 1.2.0-alpha, and the stable line before it is 1.0.8.1.

## FAQ

### How do I use Gooey with an existing argparse script?

Import Gooey and place the @Gooey decorator on the function that holds your argparse declarations, usually main. Gooey then parses the script for ArgumentParser references and builds the window from the actions it finds. For explicit widget control, replace ArgumentParser with GooeyParser and set widget on each argument.

### What is Gooey in computing terms?

It is a Python library that converts a Python 3 console program into a desktop GUI application. It attaches through a decorator and maps argparse actions to wxPython widgets rather than requiring you to build an interface.

### How do I install Gooey?

The README gives pip install Gooey as the easiest route, or cloning the repository and running python setup.py install. setup.py requires Python 3.6 or later and depends on wxpython>=4.1.0 along with Pillow, psutil, colored, pygtrie and re-wx.

### Does Gooey support optparse?

No. The README states that the older optparse is currently not supported, and that Gooey parses the script for references to ArgumentParser. Scripts still using optparse need their parsing converted before Gooey can build a window from it.

### Is Gooey suitable for scripts whose output is piped to another program?

The README places those outside its target. It says that if you are building utilities for yourself, for other programmers, or something whose result you want to capture and pipe to another console application, Gooey probably is not the tool for you. It is aimed at run-and-done scripts used by non-programmers.

## Sources

- [chriskiehl/Gooey on GitHub](https://github.com/chriskiehl/Gooey)
- [Issues](https://github.com/chriskiehl/Gooey/issues)
- [License: MIT](https://github.com/chriskiehl/Gooey/blob/master/LICENSE)
- [README](https://github.com/chriskiehl/Gooey/blob/master/README.md)
- [Releases](https://github.com/chriskiehl/Gooey/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chriskiehl-gooey