Skip to main content
`Ctrl`+`K`

# 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 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()

Before we can run the example application we need to install PyGObject, GTK, and their dependencies. Follow the instructions for your platform below or use a cross-platform package manager like conda or Pixi.

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

Ubuntu | Fedora | Arch Linux
Windows | macOS | openSUSE
Conda | Pixi | from Source

After running the example application have a look at the Tutorials for an overview of how to create GTK apps and the GNOME Python API docs for API documentation for all supported libraries.

## Windows

1. Go to https://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-python mingw-w64-ucrt-x86_64-python-gobject`

   Note

   While some systems may use `python3` in the package name, current MSYS2 UCRT64 environments typically use `python`. If one fails, try the other (incl. step 8).

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 `python 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 libgirepository-2.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`

## conda

1. Go to https://docs.conda.io and install Miniconda or Miniforge

2. Open a terminal

3. Execute `conda create --channel conda-forge --name pygobject pygobject gtk4`

4. Execute `conda activate pygobject`

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

6. Run `python hello.py`

## Pixi

1. Go to https://pixi.sh/latest/installation/ and install pixi

2. Place your `hello.py` script into a separate `hello` directory

3. Open a terminal and `cd hello`

4. Execute `pixi init .`

5. Execute `pixi add pygobject gtk4`

6. Run `pixi run python hello.py`

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