Linux/Unix (GTK)¶
The Toga backend for Linux (and other Unix-like operating systems) running the GNOME desktop environment is toga-gtk.
GTK on Windows and macOS
Although GTK can be installed on Windows and macOS, and the toga-gtk backend may work on those platforms, this is not officially supported by Toga. We recommend using toga-winforms on Windows, and toga-cocoa on macOS.
Prerequisites¶
toga-gtk requires Python 3.10+, and GTK 3.22 or newer.
Most testing occurs with GTK 3.24 as this is the version that has shipped with all versions of Ubuntu since Ubuntu 20.04, and all versions of Fedora since Fedora 32.
The system packages that provide GTK must be installed manually:
These instructions are different on almost every version of Linux and Unix; here are some of the common alternatives:
Ubuntu 24.04+ / Debian 13+¶
(venv) $ sudo apt update
(venv) $ sudo apt install git build-essential pkg-config python3-dev libgirepository-2.0-dev libcairo2-dev gir1.2-gtk-3.0 libcanberra-gtk3-module
You can use deadsnakes (or a similar third-party source) to install a Python version other than the system default by replacing python3-dev with the -dev package matching the desired Python version. For example, to use Python 3.12, replace python3-dev with python3.12-dev.
Ubuntu 22.04 / Debian 11, 12¶
(venv) $ sudo apt update
(venv) $ sudo apt install git build-essential pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-gtk-3.0 libcanberra-gtk3-module
You'll also need to add a pin for PyGObject < 3.52.1 to your Python dependencies. Later versions of PyGObject require the libgirepository-2.0-dev library, which isn't available on older Debian-based distributions.
You can use deadsnakes (or a similar third-party source) to install a Python version other than the system default by replacing python3-dev with the -dev package matching the desired Python version. For example, to use Python 3.12, replace python3-dev with python3.12-dev.
Fedora 41+¶
(venv) $ sudo dnf install git gcc make pkg-config python3-devel gobject-introspection-devel cairo-gobject-devel gtk3 libcanberra-gtk3
You can use a Python version other than the system default by replacing python3-devel with the -devel package matching the desired Python version. For example, to use Python 3.12, replace python3-devel with python3.12-devel.
Arch / Manjaro¶
(venv) $ sudo pacman -Syu git base-devel pkgconf python3 gobject-introspection cairo gtk3 libcanberra
You can use a Python version other than the system default by replacing python3 with the package for the desired Python version. For example, to use Python 3.12, replace python3 with python312.
OpenSUSE Tumbleweed¶
(venv) $ sudo zypper install git patterns-devel-base-devel_basis pkgconf-pkg-config python3-devel gobject-introspection-devel cairo-devel gtk3 'typelib(Gtk)=3.0' libcanberra-gtk3-module
You can use a Python version other than the system default by replacing python3-devel with the -devel package matching the desired Python version. For example, to use Python 3.12, replace python3-devel with python3.12-devel.
FreeBSD¶
(venv) $ sudo pkg update
(venv) $ sudo pkg install git gcc cmake pkgconf python3 gobject-introspection cairo gtk3 libcanberra-gtk3
You can use a Python version other than the system default by replacing python3 with the package for the desired Python version. For example, to use Python 3.12, replace python3 with python312.
Other distributions¶
If you're not using one of these distributions, you'll need to work out how to install the developer libraries for python3, cairo, and gobject-introspection (and please let us know so we can improve this documentation!)
In addition to the dependencies above, if you would like to help add additional support for GTK4, you need to also install gir1.2-gtk-4.0 on Ubuntu/Debian, or gtk4 on Fedora or Arch. For other distributions, consult your distribution's platform documentation.
If you would like to run the GTK4 backend with libadwaita on GNOME, install gir1.2-adw-1 on Ubuntu/Debian or libadwaita on Fedora or Arch. For other distributions, consult your distribution's platform documentation.
Some widgets (most notably, the WebView and MapView widgets) have additional system requirements. Likewise, certain hardware features (Location) have system requirements.
See the documentation of those widgets and hardware features for details.
Toga has experimental support for GTK 4. GTK 4 support requires a Linux distribution that provides libgirepository 2.0. This means it is not possible to use the GTK 4 backend on Debian 11, Debian 12, Ubuntu 22.04, or any other older Debian-based distribution.
Installation¶
toga-gtk is installed automatically on any Linux machine (machines that report sys.platform == 'linux'), or any FreeBSD machine (machines that report sys.platform == 'freebsd*'). It can be manually installed by running:
$ python -m pip install toga-gtk
GTK 4 support (experimental)¶
The experimental GTK 4 backend requires the use of GTK 4.10 or newer. This requirement is met by Debian 13, Ubuntu 24.04, and Fedora 41. Most testing occurs with GTK 4.14, as this is the version that ships with Ubuntu 24.04.
If you want to use the experimental GTK 4 backend, run:
$ python -m pip install toga-gtk[gtk4]
and set the TOGA_GTK environment variable:
$ export TOGA_GTK=4
The experimental GTK 4 backend also aims to provides support for integrating with desktop environment-specific libraries. At present, libadwaita is the only supported library of this kind. This functionality requires libadwaita 1.5 or newer. libadwaita integration is automatically enabled on GNOME desktops if GTK4 support is enabled, and automatically disabled on non-GNOME desktops when using GTK4. To explicitly enable integration with libadwaita, set:
$ export TOGA_GTKLIB=Adw
To explicitly disable integration with libadwaita, set:
$ export TOGA_GTKLIB=None
An unset or empty $TOGA_GTKLIB will trigger automatic detection.
Most testing occurs with libadwaita 1.5, as this is the version that ships with Ubuntu 24.04.
We have no immediate plans to integrate with tauOS's libhelium or elementaryOS's Granite, but we're open to contributions adding support for these libraries.
Implementation details¶
The toga-gtk backend uses the GTK3 API. The experimental GTK 4 toga-gtk backend uses the GTK4 API.
The native APIs are accessed using the PyGObject binding.