PyGObject

3.56.2 · active · verified Mon Apr 13

PyGObject is a Python package providing bindings for GObject-based libraries, including GTK, GStreamer, WebKitGTK, GLib, and GIO. It allows Python applications to interact with the entire GNOME software platform through GObject Introspection. The current version is 3.56.2 and it supports Linux, Windows, macOS, and Python 3.10+.

Warnings

breaking The `pygtkcompat` module, used for porting legacy GTK2/Python2 code, was deprecated in PyGObject 3.48 and entirely removed in 3.52.0. Code relying on this compatibility layer will break.
Fix: Migrate code fully to modern PyGObject and GTK3+ APIs. Refer to PyGObject's 'Porting from Static Bindings' documentation.
breaking PyGObject 3.55.0 removed 'toggle references'. If you used Python weakrefs to track PyGObjects, you must change them to `GObject.Object.weak_ref()`.
Fix: Replace Python weakrefs with `GObject.Object.weak_ref()` for tracking GObjects.
gotcha Installing PyGObject via pip often requires system-level development packages (e.g., GTK development files, gobject-introspection, a C compiler) which are not installed by `pip`. The `pip install` command is primarily for the Python bindings, not the underlying GObject/GTK libraries.
Fix: Follow platform-specific installation instructions for system dependencies (e.g., `sudo apt install python3-gi gir1.2-gtk-4.0` on Debian/Ubuntu, MSYS2 for Windows) before `pip install PyGObject`.
gotcha When importing `Gdk` or `Gtk`, their `init_check()` functions are automatically called for backwards compatibility. This prevents calling `Gtk.disable_setlocale()` as it must be called before GTK initialization.
Fix: To skip auto-initialization, call `gi.disable_legacy_autoinit()` before importing `Gdk` or `Gtk`.
deprecated Calling GLib API through the GObject namespace (e.g., `GObject.some_glib_function()`) was deprecated in PyGObject 3.7.2. This usage will likely be removed in future versions.
Fix: Call GLib API directly through the `GLib` namespace (e.g., `GLib.some_function()`) after importing `GLib` from `gi.repository`.

Install

pip install PyGObject PyPI (requires system dependencies)

Imports

gi
```
import gi
```
Old static bindings (e.g., 'import gtk' for GTK2) are deprecated and no longer supported in modern PyGObject versions, which use GObject Introspection via 'gi.repository'.
Gtk
```
from gi.repository import Gtk
```
Accessed through the 'gi.repository' namespace after calling 'gi.require_version()'.
require_version
```
gi.require_version('Gtk', '4.0')
```
It is crucial to call gi.require_version() before importing from gi.repository to specify the desired version of a library (e.g., GTK 4.0), preventing conflicts or unexpected behavior if multiple versions are installed on the system.

Quickstart

This 'Hello World' example demonstrates a basic GTK4 application using PyGObject. It initializes the GTK4 library, creates a Gtk.Application, and displays a window with 'Hello World' as its title.

import gi
gi.require_version('Gtk', '4.0')
from gi.repository import GLib, Gtk

class MyApplication(Gtk.Application):
    def __init__(self):
        super().__init__(application_id="com.example.MyGtkApplication")
        GLib.set_application_name('My Gtk Application')

    def do_activate(self):
        window = Gtk.ApplicationWindow(application=self, title="Hello World")
        window.present()

app = MyApplication()
app.run()

view raw JSON →