Translation(s): English - 简体中文

(!) ?/Discussion


A pragmatic guide to creating a simple Debian package.

This ?HowTo is intended to show that Debian packaging is not that hard. Since Debian packaging is not that hard, why shouldn't plain beginners understand and do it, too?

As a teaser, here's a short list of some reasons to package a program:



  1. Introduction

    1. 1. Contents

      1. Why does this page even exist?

      2. Creating the package

        1. Initial compilation

        2. ''Debianization''

        3. Initial compilation of the package

        4. All tests in chroot

        5. Testing the package

        6. Lintian

        7. Piuparts

        8. Check points for any package

        9. Examples

      3. Advanced Packaging Procedures

      4. External useful links

      5. Useful pages

Why does this page even exist?

Since the Debian Policy and the Debian New Maintainers' Guide sometimes are too big to read for people who prefer a more pragmatic approach to problems, this ?HowTo will focus on a pragmatic approach to learning how to create Debian packages.

The Debian package management chapter of the Debian Reference contains lots of useful information for handling all kinds of problems one runs into with apt and dpkg.

Creating the package

If the information below doesn't answer your questions, please look in the New Maintainer's Guide and in Debian Policy

If you want to create an official debian package, make sure it's not already packaged. If somebody is working on the package, you should contact them if you intend to make an official package together. More info is in the New Maintainer's Guide.

Initial compilation

Before starting there are some risks you should be aware of:



It is best to create a chroot jail in which to build the application. This mitigates security and system corruption problems. In addition it ensures that any local changes to your machine will not interfere with the build.

If the package compiles, then it means you may have figured out all the dependencies. Don't worry, this will be checked later in a chroot environment. Try the application in a chroot environment (some things might be needed in the chroot jail - for example, proc may need to be mounted, sys to be mounted, etc.). Broken installation scripts are, unfortunately, very common and you probably don't want to run a test installation yet. You might prefer doing the tests in a qemu virtual machine in snapshot mode - changes are not permanent in snapshot mode and you can keep you development machine safe from malitious/broken makefiles.


After the first compilation, it's time to create the Debian specific part of the package.

Debianize the package by using dh_make.

File debian/control: Add to the Build-Depends (sometimes even Build-Depends-Indep) the list of packages needed to be installed for the application to compile (remember the list done previously). You should leave out any packages that are listed in /usr/share/build-essential/essential-packages-list or /usr/share/build-essential/list and also leave out any packages that listed as dependencies by any of those packages. More detailed information cane be found on the page about ?control file creation for the new package.

File debian/rules: If any quirking was done then:

Review each of the template files (debian/*.ex). If your package needs that feature, then customize the file as needed and rename it without the ".ex".

Delete all the unneeded templates. Don't worry, they can be restored at any time with "dh_make -a".

Make sure that all the directories you will place files in are listed in the debian/dirs file without a leading slash (/).

Make sure that the files are installed in the proper place (under a directory, not on the root system). Take care at the install target from the application makefile. If the application uses autoconf and automake, it may be enough to set the environment variable DESTDIR, e.g. "make DESTDIR=$(CURDIR)/debian/packagename". (dh_make will set this up automatically.)

Note: very often the upstream package will install files under /usr/local. DO NOT INSTALL ANY FILES IN THERE.

Initial compilation of the package

TODO: add notes

All tests in chroot

Why is it a good idea to use a chroot?

Testing the package

licensecheck -r *

TODO: add notes


Test all the packages with lintian.

lintian package-version.changes


Test all the .deb packages with piuparts.

piuparts binpackage-version.deb

Check points for any package

This page is still incomplete; please help by adding information to it. Do not forget that the information here should be in a concise form.


Advanced Packaging Procedures

Useful pages