Python GTK+ 3 Tutorial

One of the big advantages of PyGTK is that it is documented very well. Unfortunately, despite the efforts to make PyGObject as compatible to PyGTK as possible, the differences are still huge. A big portion is due to the changes between GTK+ version 2 and 3, of course. To date, you basically have to look into the GIR file or C reference manual to try to figure out how things work. Once you are familiar with the way C functions are converted to Python, you can guess most methods. For a beginner this is far from obvious, though.

During this years Desktop Summit first efforts were made to come up with a generic solution to generate API documentation for language bindings. However, the Python bindings provide additional and slightly different (mostly due to PyGTK compatibility) methods and classes. This information is not included in the API docs for C, which constitutes an additional obstacle.

To address some of this issues, especially for beginners, I started writing a tutorial that gives an introduction to writing GTK+ 3 applications in Python. My work is based on an updated version of the PyGTK tutorial, the gtkmm 3 tutorial, and the GTK+ 3 reference manual. The current version of the tutorial is available at ( You'll need at least PyGObject 2.90.3 for all examples to work correctly.

The goal is to provide an introduction to the most important widgets and concepts, rather than an API documentation. It is still far from complete, but I think it's enough to make it available for the broader audience. More technically, it is based on Sphinx and most of the contents were copied from one of the sources mentioned above. As always, help is highly appreciated. The code currently lives in my github repository.


Hi! This sounds great, I was actually looking for something like this today and didn't really find anything good.

It seems a really good iniciative ! Thanks for doing this ;-)

Wow! Thanks for working on this!

You might want to consider activating the ReadTheDocs "Service Hook" for
your github repo and make this tutorial available on That way,
you have updated builds at each commit/push and you raise PyGObject's visibility
a bit within the Python community. And it saves you some manual labor. Well, at
least until all this moves to, if/when you decide to do that :)

Thank you very much for your work, it's an incredible tutorial. I'm looking for it during last months, but I didn't find anything like this.

Thank you

Great tutorial. I found it odd that you always used to instantiate a box rather than just Gtk.Box(...). And you did not explain why.

Also, for PyGTK experts, it may be useful to have a section on the differences to consider when porting an application.

In reply to by Michel (not verified)

Thanks for pointing this out. Gtk.Box(...) didn't work with earlier versions of PyGObject, but it's fixed now. I removed all occurrences of

Great tutorials! I need more examples on dnd and how targets work. Can you extend your DnD example with one more icnoview that you can dnd the pixbuf and the text to. I do not know how to change your code to do that. Either it shows the pixbuf or it shows the text not both at the same time, as I want it :)