Debian Packaging for PyGTK+3 project

Hello to everyone!!
Could you please give me some pointers about how to create a .deb package for a PyGTK+3 project (Python 3).
There is a lot of documentation online about “debian packaging”, but it may not be updated and / or specific for Python 3 or GTK+3. And since time is limited, before starting to study difficult libraries, I would like to be sure they are the ones I actually need =) Some guides mention “Autotools”, others “Setuptools” and so on.

  • Which are the most frequently used ways to package a PyGTK+3 project?
  • Which are their pros and cons?
  • Could you point me to some updated and useful resources?

P.s. Maybe my understanding is wrong, but there seems to be a “proper” (and probably longer/more complicated) way if you want your package to be included in the official repositories, or “quicker” ways if you just want it to work.


is there any specific reason you are looking for pygtk3 instead of using pygobject?

1 Like

This is the reference documentation that I have used for the application development:

Sample hello world template:

I suppose it is using PyGObject underneath, but I’m not sure. Please have a look at it yourself.
Thank you very much

Yes, that’s python-gobject, which replaced pygtk. You don’t need to package it, the debian package is python3-gi

I think you have misunderstood my question.
I’m not trying to package python-gobject itself (which, as you pointed out, already exists).
I have created a new software (using python-gobject) and I want to distribute it to other people.
Do you understand?

For example, let’s say that I have created a Hello-World software like the following one and now I want to generate a .deb package for it so that other people can download the .deb package from my website and install this Hello-World software on their computer. (As a bonus, it would be nice to make my program available to the public through the OS software manager).

import gi

gi.require_version("Gtk", "3.0")
from gi.repository import Gtk

win = Gtk.Window()
win.connect("destroy", Gtk.main_quit)

To distribute your software you have two options:

  • use Flatpak and depend on the GNOME run time to ensure the presence of GTK and pygobject
  • use the Debian packaging format (deb)

You’ll also have to learn how to package a Python application, using setuptools or, if you’re writing a Linux desktop app, you may want to learn a build system like Meson.

Thank you @ebassi for your help. It is highly appreciated.

If not insanely difficult, I would strongly prefer to avoid Flatpak and use the Debian packaging format.
I don’t mind putting some effort into learning something useful.
I have written a Linux desktop application (with a graphical interface etc) and plan on releasing it as open source and make the git repository public.
I’ve already done some research in order to choose the appropriate open source licence. Now I need to learn how to package it.

Can you please give me some pointers about that? Then I will go on and do some reasearch based on your suggestions…

P.s. Are Setuptools and Meson alternatives or will I need to use both? Pros and cons?

Packaging something with Deb is not “insanely” difficult, but it’s definitely harder than Flatpak. Additionally, if you want your app to be picked up by Debian itself, you’ll have to learn a lot more about packaging than the basics.

In any case, you may start from this:

Personally, even for Debian, I’d still strongly recommend using Flatpak; pointing people to a deb package hosted somewhere is not what I consider a good end user installation story; and setting up a Debian archive for people to install via apt is even worse.

Setuptools is usually what Python libraries and applications use to install themselves.

Meson is more generic, and targets multiple languages.

The pro for setuptools is that it’s pretty much what Python developers already expect; the con is that you have to deal with the integration of all the desktop-related things you’re going to need: desktop files; possible MIME type registration; GSettings schemas; help and documentation; icons; GResources; etc.

Meson can be more complex, but it covers all needed use case—given that it’s also what most GNOME apps use.

I was thinking to use a downloadable .deb package (or even a personal PPA if feasable) at the beginning and then, if everything goes well, submit it to Debian.

I think Meson should be the right way.

I’ve already started reading the Debian packaging link you gave me (I found it a while ago) but it is a little bit unclear since many times it assumes that the “upstream source” is already ready for packaging (upstream tarball, etc)…

I create a deb package for software I use internally. I couldn’t get any of the packaging tools working for me, because of all the different types of files (.py, .ui, odt, etc). Probably due to shortcomings on my part. I ended up using a quick and dirty python script to organize the folder/files and then use dpkg-deb to roll it into a deb package. This thread is of real interest to me. Could you post your successes and failures here?

1 Like

Hi @theGtknerd !! Thank you for your interest in this topic.
Honestly, I was very surprised to find so little information online. I would have expected to find lots of tutorials by googling keywords like “meson”, “python”, “debian”. I am currently trying to go through the meson documentation and the debian guide for new maintainers.

I think this topic is extremely important since knowledge about packaging is mandatory to allow new software to enter the Linux ecosystem. Moreover, the availability of beginner-level training resources would contribute to increase the number of debian maintainers (which would be highly beneficial to the project).

If anyone inside the GNOME Community has knowledge about this topic and desires to share it, I think a small webinar on the subject would be very nice and well-received .

If you specifically want to package for Debian, the guide you need is the New Maintainers’ Guide

Thank you @nmcgovern for your suggestion,
I’ve already started going through all the Debian docs/wikis.

It’s interesting but I still think that this topic is one of those cases in which seeing a quick (even unrefined) video tutorial of a simple example would help a lot while studying the documentation. Learning the theory should go hand in hand with seeing a real-world application.
The Debian documentation is huge because it has to cover every case; thus it seems something you should consult to solve a specific research-question AFTER you have a general idea of how things should be done (standard workflow). But 70% of it is probably unnecessary for a quick example.

Anyway (reading through the debian documentation) it seems that before packaging the software, the upstream developer has to create the “tarball” (which represents the starting point of the debian-packaging process). The tarball is the result of “compiling” the software, right? And I can compile my Python project with Meson, right?

Here’s a quick example. To create a basic Debian package, you need to—

  1. Create a new directory called debian at the root of your project directory. Inside this directory, create these files:

    • control, which contains the name, description, and dependencies of your package,
    • rules, which basically tells it how to build your package,
    • changelog, a change log of your program

    You can try to write these files yourself by following the documentations, using tools like debmake or dh_make to help generate them. Or, more simply, you can just look at how other projects are packaged and imitate them.

  2. After setting up the files in the debian directory, you can now run dpkg-buildpackage -us -uc to create the .deb file.

A tarball is just an archive file. It often refers to source code tarballs, which contains the source of your program. A tarball is used simply for downloading a version of the software, so you can create a package out of it. If you are packaging your own software, you don’t necessarily have to first make a tarball in order to make a package. You can add Debian packaging information directly to your source code tree.

I’ll try and do an ELI5-style (Explain Like I’m Five) explanation of everything. A bit long but hopefully would be helpful to someone reading this thread.

Before users can use your program, they need to (1) download it, and (2) install it.

First, downloading — It’s usually much more convenient to download a tarball (a compressed file containing all the files of the program) than to download each file separately. This is why tarballs are provided by developers. In some cases, people might prefer cloning the git repo instead of downloading a tarball.

Second, installing — Installing means copying files to specific locations on the user’s computer so they can be accessed. But there’s one problem: very often, the source code is not directly usable—you need to process the source code in some way before installing. This usually involves compiling the source code, but often there are other things that you need to do (e.g. generating translation files). This whole process is known as building. If the program is only a single hello-world script, you probably don’t need to process it before installing it. But things can get complicated when you have many files and many things that you want to do before or even after installing. You can still do everything manually, if you want. But it’s usually easier to use a build system like Meson to automate this process.

When you create a Debian package, what you’re doing is essentially building your software and “installing” it onto the .deb file. If you inspect a .deb file (which is just an archive file that you can open with an archive manager), you’d see that it contains not the source, but the processed (e.g. compiled) result of the source. But this is all still contained in the .deb file. Only when the user actually installs the .deb file will the contents be copied to the specified locations on the user’s system.

Here are some simplified diagrams that I hope will make things clearer.

Diagram 1. Installing directly from source. In this simple case, there’s no build step and no build system, because the source code is, for example, only a single Python script file that can be run as is by the user.

   (simply copy the files to the user's system)
┌─────────────┐       │                               ┌────────────────┐
│ Source code ├───────┴───────────────────────────────┤ Installed code │ 
└─────────────┘                                       └────────────────┘

Diagram 2. Building and installing from source, using a build system.

            Building and installing
              (e.g. with Meson)
             Building               Installation
           instructions             instructions
                 │                        │
┌─────────────┐  │    ┌────────────────┐  │           ┌────────────────┐
│ Source code ├──┴────┤ Processed code ├──┴───────────┤ Installed code │ 
└─────────────┘       └────────────────┘              └────────────────┘

Diagram 3. The contents of the .deb package, marked by the dashed border.

            Building and installing
              (e.g. with Meson)  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
                 ┌────┴──────────┆───────┐       ╎
             Building            ╎  Installation ╎
           instructions          ╎  instructions ╎
                 │  ╭╌╌╌╌╌╌╌╌╌╌╌╌┘        │      ╎
┌─────────────┐  │  ╎ ┌────────────────┐  │      ╎    ┌────────────────┐
│ Source code ├──┴──╎─┤ Processed code ├──┴──────╎────┤ Installed code │ 
└─────────────┘     ╎ └────────────────┘         ╎    └────────────────┘
                             .deb package

Diagram 4. Simplified view of the workflow when building and installing with the .deb package. Compare this with the previous diagram.

             Developer                         User installs
             builds .deb                       .deb package
                 │                                  │
┌─────────────┐  │  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮  │ ┌────────────────┐
│ Source code ├──┴──┤        .deb package        ├──┴─┤ Installed code │ 
└─────────────┘     ╰╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯    └────────────────┘

If you want it to be included in Debian’s repositories, you need to follow their policies and procedures, which, depending on the situation, can be a lot more complicated than just building a .deb that just “works”. Usually it’s better to see if an existing Debian maintainer is willing to create and maintain the package for you. This is what most people do, traditionally. Developers are responsible for writing applications, and maintainers are for packaging them.

If you want to package and distribute things yourself, you will probably be better served by Flatpak, which is made with the goal of enabling upstream packaging—it makes distributing software much easier for the upstream developer. It’s probably the quickest way to make your program available to the public.


Thank you very much @johnfactotum for your answer. It has already been very helpful.
I will focus on learning Meson and trying to build a .deb package like you described.
Then I will try to find a maintainer for the official debian packaging, even if I would like to learn to create official deb packages myself in the long run.
P.s. Thank you again for your time and effort. After implementing mathematical algorithms in Python, I found myself stuck when trying to accomplish an apparently simple task like distributing the software… So here I am, asking a question that sounds like “How do I create an HTML file?”… ahahahahah XD … It is also a bit frustrating for me, but I think that this can be the first step in discovering a new world full of interesting things to learn

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.