Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 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. There are also 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.

## 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`

## 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`

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