PyGObject Stubs

2.17.0 verified Fri May 01 auth: no python

Typing stubs for PyGObject, providing type hints for GLib, GObject, Gtk, Gdk, Gio, and other GNOME libraries. Version 2.17.0 supports Python >=3.10. This package enables static type checking (mypy, pyright) for PyGObject code and is actively maintained alongside PyGObject releases. Release cadence is irregular, tied to GNOME releases and bug fixes.

pip install pygobject-stubs

Common errors

error Cannot find implementation or library stub for module 'gi.repository.Gtk' ↓

cause pygobject-stubs not installed or not found by mypy because stubs are not in the MYPYPATH.

fix

Install pygobject-stubs with pip, and ensure mypy sees it (automatic in virtualenv). For custom environments, set MYPYPATH to the site-packages of the venv.

error from gi.repository import Gtk; TypeError: 'gi.repository' is not a package ↓

cause PyGObject runtime library (libgobject-introspection) not installed or gi module not found.

fix

Install system packages: libgirepository1.0-dev (Ubuntu/Debian), glib2-devel (Fedora), or glib-devel (macOS via Homebrew). Then reinstall PyGObject.

error No overloads of 'Gtk.Window.new' match argument types (int) ↓

cause Stubs define Gtk.Window.new with Gtk.WindowType enum, but often code passes an integer (e.g., 0). Enum is required for type checking.

fix

Use Gtk.WindowType.TOPLEVEL instead of raw integer. If stub mismatch, cast: Gtk.Window.new(Gtk.WindowType(0))

Warnings

gotcha Stubs are NOT complete: many functions have missing or overly generic type hints. Use `Any` or `# type: ignore` for uncovered APIs. ↓

fix Run mypy with --strict only if you accept suppressing many errors, or use --warn-unused-ignores to track where stubs are missing.

gotcha Install order matters: pygobject-stubs must be installed AFTER PyGObject to ensure correct bytecode compilation. Otherwise, stubs may not be recognized. ↓

fix Install PyGObject first: pip install PyGObject && pip install pygobject-stubs

deprecated Stubs for GTK3 vs GTK4 are separate; pygobject-stubs covers GTK3. For GTK4, use gtk4-stubs (not included). ↓

fix If targetting GTK4, install gtk4-stubs and use from gi.repository import Gtk4 (if available)

gotcha mypy version incompatibility: old mypy (<0.990) may fail to find stubs. Ensure mypy >=1.0 for best results. ↓

fix Upgrade mypy: pip install 'mypy>=1.0'

Install

pip install 'pygobject-stubs>=2.17.0'

Imports

Gtk.Window

wrong

from gi import Gtk; win = Gtk.Window()

correct

from gi.repository import Gtk; win = Gtk.Window()

The 'gi.repository' submodule is required for correct stubs resolution.

GLib.MainLoop

wrong

import GLib; loop = GLib.MainLoop()

correct

from gi.repository import GLib; loop = GLib.MainLoop()

GLib is part of the gi.repository namespace, not a top-level module.

Quickstart

Quickstart example showing correct import pattern and basic usage for type-checking.

from gi.repository import Gtk, Gio

# Attempt to get the default display (succeeds only if running under X11/Wayland)
display = Gdk.Display.get_default()
if display is None:
    raise RuntimeError('No display available: ensure DISPLAY or WAYLAND_DISPLAY is set')
# Example: create a simple window (won't show without main loop; just for type-checking)
win = Gtk.Window.new(Gtk.WindowType.TOPLEVEL)
win.set_default_size(200, 200)
win.show_all()
# Type-check with mypy: mypy --enable-incomplete-feature=GenericParenTypeHints script.py