Guide · Open source

How to use Gooey: turn a Python script into a GUI app

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Gooey is a Python library that wraps an existing command-line script in a graphical window. You add a decorator to the function that holds your argparse declarations, and Gooey builds a form from those arguments so people can fill in options with buttons and text boxes instead of typing commands. This guide covers installation, the basic decorator, the GooeyParser widget control, and the cases where Gooey is a poor fit.

Gooeychriskiehl/Gooey · ★ 21.9k · MIT Install options & downloads

Quick start

1Install Gooey. Run pip install Gooey in the environment where your script runs.
2Find your argparse function. Locate the function that builds your ArgumentParser, usually main.
3Add the decorator. Import Gooey from the gooey package and place @Gooey above that function.
4Optionally use GooeyParser. Replace ArgumentParser with GooeyParser and set widget on arguments such as FileChooser or DateChooser.
5Tune the window. Pass options such as program_name, default_size or required_cols to the decorator if the defaults need changing.
6Run the script. Run your script normally. The GUI opens and the user fills in the form instead of typing arguments.

Install Gooey with pip

The easiest way to install Gooey is with pip, the Python package manager, from PyPI. Gooey runs on Python, so you need Python installed first.

pip install Gooey

Attach Gooey to your argparse script

Gooey is attached to your code with a decorator on the function that has your argparse declarations, usually main. Import Gooey, put @Gooey above the function, and keep the rest of your code as it is. Gooey parses the script for ArgumentParser references and builds the GUI from them.

Gooey also accepts options in the decorator, such as program_name, default_size, required_cols and optional_cols. The README lists these along with auto_start, which skips the config screens, and monospace_display, which uses a monospaced font in the output screen.

program_name defaults to the script name
program_description defaults to the ArgumentParser description
required_cols and optional_cols set the number of columns in the Required and Optional sections
dump_build_config and load_build_config save and reload the JSON that Gooey uses to configure itself

from gooey import Gooey

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

Choose specific widgets with GooeyParser

Gooey picks sensible default widgets from the options it finds. If you want control over which widget appears, use GooeyParser in place of ArgumentParser. It is a drop-in replacement and adds a widget keyword argument. The README notes you do not have to change the rest of your argparse code.

The README gives FileChooser and DateChooser as examples of widget names.

store maps to a text box (TextCtrl)
store_true, store_false, store_const and version map to a checkbox
choice maps to a dropdown
A mutually exclusive group maps to a radio group

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")
  ...

Try the example scripts

The Examples Repository linked from the README contains ready-to-run scripts that show Gooey's layouts, widgets and features. Download them to see how different arguments produce different forms before writing your own.

Know when Gooey is the wrong tool

Gooey is aimed at run-and-done scripts and tools for non-programmers. The README says it is not meant for scripts whose output is piped into other command-line programs. It also says the older optparse is not supported, so the script must use argparse. Python 2 is no longer supported; older releases need a pinned version and a manually installed wxPython.

Output piped to another command-line program: not supported by design
optparse projects: not supported
Python 2: pin an older release and install wxPython manually

What people use it for

Giving colleagues a form to move or process files without using a terminal
Building a simple internal office utility with file and date pickers
Adding a quick GUI front end to a hobby or student Python script
Creating multi-option tools for non-programmer end users

Frequently asked questions

Is Gooey free to use?

Gooey is released under the MIT licence, as stated in the project's repository. The MIT licence permits use, including in commercial work, subject to its terms, so check the licence text for your own case.

How do I install Gooey?

Install it from PyPI with pip install Gooey. The README also describes cloning the repository and running setup.py, but pip is the easiest route.

Does Gooey support Python 2?

No. The README says Gooey no longer supports Python 2. Python 2 users must pin an older release and install wxPython manually, since wxPython cannot be installed through pip alongside Gooey.

Can Gooey wrap a script that uses optparse?

No. The README says optparse is currently not supported, so the script needs to use argparse declarations.

Why does my Python script work in the terminal but not as a Gooey form?

Gooey builds its form from argparse declarations, so the arguments must be defined inside the function decorated with @Gooey. Scripts that depend on output being piped into other command-line programs are outside the tool's intended use, according to the README.

How does Gooey compare with PySimpleGUI, Typer, Click or Streamlit?

Gooey wraps an existing argparse script in a GUI with one decorator. PySimpleGUI is a general GUI toolkit where you lay out windows yourself. Typer and Click build command-line interfaces, and Streamlit builds web apps, so they solve different problems from Gooey.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Gooey suits developers who already have an argparse script that non-programmers need to run without a terminal, especially for run-and-done file tasks. Skip it if your script's output feeds other command-line tools, if you use optparse, or if you need Python 2, and consider a general GUI toolkit such as PySimpleGUI for a custom interface.

Install options & downloads