The Button widget is commonly used to allow a user to run a command or operation. It can display text and/or icons and provides an easy way for the user to interact with the application.


The Button can be constructed using the following:

button = Gtk.Button(label)

The label parameter used in the first constructor allows the entering of text to display on the Button.


To set the text on the Button after construction:


Images can also be set on Button widgets with:


By default, all Button widgets have a border around them. This can be configured using:


The relief_style parameter can be set as follows, with the default being Gtk.BorderRelief.NORMAL. The alternatives are Gtk.ReliefStyle.HALF or Gtk.ReliefStyle.NONE.

It is good practice to use a mnemonic in the label. This requires an underscore inserted into the label (e.g. “_Cancel”). GTK+ parses the underscore and converts it into an underline beneath the following character, which the user can then access as a shortcut to the function.


When a Button is clicked, the focus is changed to that of the Button. To prevent this happening the following method can be used:


If focus is set to False, the focus will be retained on whichever widget had it last before clicking the Button.

To force a button to show an image, even if the option is disabled globally, use:



The commonly used signals of a Button are:

"clicked" (button)
"pressed" (button)
"released" (button)

The "clicked" signal is emitted when the user presses, then releases the mouse button when on the Button. A "pressed" signal emits when the mouse button is pressed above the Button while "released" emits when the mouse button is released over the Button. In most cases, the "clicked" signal should be used.


Below is an example of a Button:

#!/usr/bin/env python3

from gi.repository import Gtk

class Button(Gtk.Window):
    def __init__(self):
        self.connect("destroy", Gtk.main_quit)

        button = Gtk.Button(label="Button")
        button.connect("clicked", self.on_button_clicked)

    def on_button_clicked(self, button):
        print("Button has been clicked!")

window = Button()


Download: Button