Skip to content

GTK

UI & GraphicsGUIC
Official docs ↗GitHub ↗

What it is

GTK (GIMP Toolkit) is a multi-platform toolkit for creating graphical user interfaces. In Python, GTK is accessible via the PyGObject library, allowing developers to build desktop applications with windows, dialogs, buttons, menus, and more.

GTK allows developers to build windows, buttons, labels, text entries, and complex layouts. It supports signals for event handling, CSS-like styling, and integration with OpenGL or Cairo for custom drawing.

Installation

pip install PyGObject

Getting started

The smallest useful thing you can do with it, and what each part means.

Simple GTK Window
import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class MyWindow(Gtk.Window):
    def __init__(self):
        super().__init__(title='Hello GTK')
        self.set_default_size(300, 200)
        button = Gtk.Button(label='Click Me')
        button.connect('clicked', self.on_button_clicked)
        self.add(button)

    def on_button_clicked(self, widget):
        print('Button clicked!')

win = MyWindow()
win.connect('destroy', Gtk.main_quit)
win.show_all()
Gtk.main()
Creates a basic GTK window with a button that prints a message when clicked.
Adding multiple widgets
box = Gtk.Box(spacing=6)
win.add(box)
label = Gtk.Label(label='Hello')
entry = Gtk.Entry()
box.pack_start(label, True, True, 0)
box.pack_start(entry, True, True, 0)
Demonstrates adding multiple widgets (label and entry) to a GTK box layout.

Advanced usage

Where the library earns its place over a simpler alternative.

Using TreeView to display data
store = Gtk.ListStore(str, int)
store.append(['Alice', 25])
store.append(['Bob', 30])
treeview = Gtk.TreeView(model=store)
renderer = Gtk.CellRendererText()
column = Gtk.TreeViewColumn('Name', renderer, text=0)
treeview.append_column(column)
column2 = Gtk.TreeViewColumn('Age', renderer, text=1)
treeview.append_column(column2)
win.add(treeview)
Displays tabular data in a GTK TreeView widget.
Using Dialogs
dialog = Gtk.MessageDialog(parent=win, flags=0, message_type=Gtk.MessageType.INFO, buttons=Gtk.ButtonsType.OK, text='Hello Dialog')
dialog.run()
dialog.destroy()
Creates and shows a simple information dialog.
Styling widgets with CSS
css_provider = Gtk.CssProvider()
css_provider.load_from_data(b'button { background-color: #3498db; color: white; }')
Gtk.StyleContext.add_provider_for_screen(Gdk.Screen.get_default(), css_provider, Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION)
Applies CSS styling to GTK widgets.
Handling events and signals
button.connect('clicked', on_button_clicked)
window.connect('destroy', Gtk.main_quit)
Connects GTK signals to callback functions to handle events like clicks and window closing.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

Gtk.main_quit not called
Ensure you connect the destroy signal to Gtk.main_quit to properly exit the application.
Widget not showing
Call `show()` or `show_all()` on the widget or parent container.
TypeError: cannot register type
Check PyGObject version compatibility with GTK version.

Best practices

  • Use Gtk.Builder and .ui files for complex layouts to separate UI from code.
  • Always call `show_all()` on windows to display all widgets.
  • Connect signals carefully to avoid memory leaks.
  • Use containers like Box, Grid, or Paned for flexible layouts.
  • Follow GTK CSS conventions to style applications consistently.

Background

Why it exists, and what it was reacting to.

GTK was originally developed for the GIMP image editor and has evolved into a widely used toolkit for creating GUI applications on Linux, Windows, and macOS. PyGObject provides Python bindings for GTK 3 and GTK 4, enabling Python developers to create native-feeling desktop applications.

Related libraries

Others in UI & Graphics for C.

← All C librariesC guide