Getting Started

To get things started we will try to run a very simple GTK based GUI application using the PyGObject provided Python bindings. First create a small Python script called hello.py with the following content and save it somewhere:

import sys

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()
exit_status = app.run(sys.argv)
sys.exit(exit_status)

Before we can run the example application we need to install PyGObject, GTK and their dependencies. Follow the instructions for your platform below.

Ubuntu

Fedora

Arch Linux

Windows

macOS

openSUSE

After running the example application have a look at the PyGObject Guide for tutorials on how to create GTK apps and the GNOME Python API docs for API documentation for all supported libraries.

For full IDE support (incl. autocomplete) you will also need typing stubs available here PyGObject-stubs.

Windows

  1. Go to http://www.msys2.org/ and download the x86_64 installer

  2. Follow the instructions on the page for setting up the basic environment

  3. Run C:\msys64\ucrt64.exe - a terminal window should pop up

  4. Execute pacman -Suy

  5. Execute pacman -S mingw-w64-ucrt-x86_64-gtk4 mingw-w64-ucrt-x86_64-python3 mingw-w64-ucrt-x86_64-python3-gobject

  6. To test that GTK is working you can run gtk4-demo

  7. Copy the hello.py script you created to C:\msys64\home\<username>

  8. In the mingw32 terminal execute python3 hello.py - a window should appear.

_images/start_windows.png

Ubuntu / Debian

Installing the system provided PyGObject:

  1. Open a terminal

  2. Execute sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0

  3. Change the directory to where your hello.py script can be found (e.g. cd Desktop)

  4. Run python3 hello.py

Installing from PyPI with pip:

  1. Open a terminal and enter your virtual environment

  2. Execute sudo apt install libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-4.0 to install the build dependencies and GTK

  3. Execute pip3 install pycairo to build and install Pycairo

  4. Execute pip3 install PyGObject to build and install PyGObject

  5. Change the working directory to where your hello.py script can be found

  6. Run python3 hello.py

_images/start_linux.png

Fedora

Installing the system provided PyGObject:

  1. Open a terminal

  2. Execute sudo dnf install python3-gobject gtk4

  3. Change the working directory to where your hello.py script can be found

  4. Run python3 hello.py

Installing from PyPI with pip:

  1. Open a terminal and enter your virtual environment

  2. Execute sudo dnf install gcc gobject-introspection-devel cairo-gobject-devel pkg-config python3-devel gtk4 to install the build dependencies and GTK

  3. Execute pip3 install pycairo to build and install Pycairo

  4. Execute pip3 install PyGObject to build and install PyGObject

  5. Change the working directory to where your hello.py script can be found

  6. Run python3 hello.py

Arch Linux

Installing the system provided PyGObject:

  1. Open a terminal

  2. Execute sudo pacman -S python-gobject gtk4

  3. Change the working directory to where your hello.py script can be found

  4. Run python3 hello.py

Installing from PyPI with pip:

  1. Open a terminal and enter your virtual environment

  2. Execute sudo pacman -S python cairo pkgconf gobject-introspection gtk4 to install the build dependencies and GTK

  3. Execute pip3 install pycairo to build and install Pycairo

  4. Execute pip3 install PyGObject to build and install PyGObject

  5. Change the working directory to where your hello.py script can be found

  6. Run python3 hello.py

openSUSE

Installing the system provided PyGObject:

  1. Open a terminal

  2. Execute sudo zypper install python3-gobject python3-gobject-Gdk typelib-1_0-Gtk-4_0 libgtk-4-1

  3. Change the directory to where your hello.py script can be found

  4. Run python3 hello.py

Installing from PyPI with pip:

  1. Open a terminal and enter your virtual environment

  2. Execute sudo zypper install cairo-devel pkg-config python3-devel gcc gobject-introspection-devel to install the build dependencies and GTK

  3. Execute pip3 install pycairo to build and install Pycairo

  4. Execute pip3 install PyGObject to build and install PyGObject

  5. Change the working directory to where your hello.py script can be found

  6. Run python3 hello.py

macOS

  1. Go to https://brew.sh/ and install homebrew

  2. Open a terminal

  3. Execute brew install pygobject3 gtk4

  4. Change the working directory to where your hello.py script can be found

  5. Run python3 hello.py

_images/start_macos.png

For more details on how to use a virtualenv with PyGObject, see the “Creating a Development Environment” page.