Installation and Setup

Setting up PyGTK means installing the binding and the GTK 2 libraries it binds, then verifying that the import works and reports the right toolkit version. The packages are the distro's python-gtk2 (or the equivalent) plus the pygobject layer it depends on, and the verification is a three-line import that prints the GTK version and the binding version. This chapter covers the package installation for the common platforms, the import check, the development-time setup (the pygtk-demo example browser and the GTK reference), and the version-compatibility check that keeps an app from running against a toolkit it was not built for.

Installing the Packages

# Debian / Ubuntu - the binding plus the GTK 2 runtime:
sudo apt-get install python-gtk2

# on a Python 3 era distro, the GTK 2 binding for python2 was
# "python-gtk2"; GTK 3 apps moved to the introspection stack:
sudo apt-get install python3-gi libgtk-3-0

# Fedora / RHEL:
sudo dnf install python2-gtk2        # PyGTK on the py2-era systems

# the library the binding needs, present when the package is:
#   libgtk-2.0, libgdk-2.0, libglib-2.0, libpango, libcairo

The package name is the distro's python-gtk2 (the PyGTK binding), and installing it pulls the GTK 2 runtime libraries with it - the binding is only the Python layer, the libgtk-2.0 and its dependency tree are what actually render the widgets. The important distinction this chapter keeps straight: python-gtk2 is PyGTK (the binding for GTK 2), while python3-gi plus libgtk-3-0 is the introspection stack (PyGObject for GTK 3) - two different installation lines that serve two different binding generations, and the later chapters teach the second one. On a system that has both, the import names are what disambiguate: import gtk is PyGTK, from gi.repository import Gtk is PyGObject.

The Import Check

import gtk

# the toolkit version the binding is talking to:
print(gtk.gtk_version())          # (2, 24, 30)

# the binding's own version (the pygtk release):
print(gtk.gtk_version_info)

# a minimal "is the loop alive" check - build nothing visible,
# just confirm the main loop enters and a timed event fires:
def tick():
    print("event loop is alive")
    return False                   # False: do not repeat

gtk.timeout_add(200, tick)
gtk.main()                          # runs until main_quit
print("loop exited cleanly")

The verification is the import plus the version print: gtk.gtk_version() reports the GTK 2 version the library resolved to (the (2, 24, x) series is what PyGTK 2.24 binds), and confirming it before writing an app catches the common failure - the import succeeding against a different toolkit than the one the code expects. The second check is the event loop itself: timeout_add schedules a function to run 200 milliseconds into the loop, and seeing it fire proves the loop is dispatching events, which is the whole runtime the app will run on. Both checks are one-liners, and running them in a fresh interpreter before the first real window is the setup discipline - a broken binding or a mismatched toolkit fails here in one line instead of failing in the middle of a widget hierarchy.

The Development Setup: pygtk-demo and the Reference

# the bundled example browser - the fastest way to see every
# widget the installed toolkit renders:
pygtk-demo

# the GTK 2 reference documentation (online, the authoritative
# API reference for the binding's C layer):
#   https://developer.gnome.org/gtk2/
# the pygtk API reference documents the Python spelling of the
# same objects:
#   https://pygtk.org/docs/

The development setup has two tools. The pygtk-demo application is the bundled widget browser - it renders every GTK widget with its properties and signals, and it is the fastest orientation to what the installed toolkit looks like and does, and the reference for "what does a GtkScale actually render." The GTK reference documentation is the authoritative API for the underlying C objects (the same names, the C calling convention), and the pygtk documentation maps them to the Python spelling the code uses. The workflow the tutorial assumes: the code in this tutorial, pygtk-demo as the visual reference for any widget's appearance, and the GTK 2 reference as the lookup for any method's exact signature - the three together cover the setup, and the app code is written against them.

The Version Compatibility Check

import gtk

# the app's minimum toolkit check - a real app's first lines:
# GTK 2.24 is the series this tutorial targets (GtkGrid, the
# improved notebook, the final 2.x feature set)
major, minor, micro = gtk.gtk_version()
if (major, minor) < (2, 24):
    raise SystemExit(
        "this application requires GTK+ 2.24 or newer")

# the same pattern guards optional features:
# features added mid-series are checked before use
if (major, minor, micro) >= (2, 24, 0):
    grid = gtk.Grid()      # available from 2.24
    # ... use the grid

The compatibility check is the guard a real app puts in its first lines: read the resolved toolkit version and exit (or degrade) if it is older than the version the code was written against. The reason is that a distro can ship a GTK 2 older than the one the developer tested against, and the failure mode - a GtkGrid reference on a 2.16 runtime - is a clean version check's job to catch at startup with a message, not an AttributeError in the middle of building the UI. The tutorial targets the GTK 2.24 series because it is the final and most complete of the 2.x line (the GtkGrid container, the notebook improvements, the file-chooser refinements), and the check makes that requirement explicit in the code. The pattern generalizes to any feature added mid-series: check the version before using the feature, and the app states its own requirements.

Summary

The setup is the package installation - python-gtk2 for the PyGTK binding (with the GTK 2 runtime it pulls), distinct from the python3-gi/libgtk-3-0 line that serves the introspection stack - and the verification, which is the import plus gtk.gtk_version() confirming the toolkit series, plus a timed event that proves the main loop dispatches. The development setup adds pygtk-demo as the visual widget browser and the GTK 2 reference as the API lookup, and the version-compatibility check - reading the resolved version and exiting below the required 2.24 - is the guard that turns a runtime mismatch into a clean startup message. The three together - install, verify, check - are the setup discipline the rest of the tutorial builds on.