Avoid a newbie packager mistake: don’t build your Debian packages with dpkg -b

In the last years, I have seen many people try to use dpkg --build to create Debian packages. Indeed, if you look up dpkg’s and dpkg-deb‘s manual pages, this option seems to be what you have to use:

-b, --build directory [archive|directory]

Creates a debian archive from the filesystem tree stored in directory. directory must have a DEBIAN subdirectory, which contains the control information files such as the control file itself. This directory will not appear in the binary package’s filesystem archive, but instead the files in it will be put in the binary package’s control information area.

And indeed, dpkg-deb is what ultimately creates the .deb files (aka binary packages). But it’s a low-level tool that you should not call yourself. If you want to properly package a new software, you should rather create a Debian source package that will transform upstream source code into policy-compliant binary packages.

Creating a source package also involves preparing a directory tree (but with a “debian” sub-directory), it’s probably more complicated than calling dpkg -b on a manually crafted directory. But the result is much more versatile: the tools used bring value by dynamically analyzing/modifying the files within your package (for example, the dependencies on C libraries that your package needs are automatically inserted).

If this is news to you, you might want to check out the New Maintainers’ Guide and the Debian Policy.

Found it useful? Be sure to not miss other packaging tips (or lessons), click here to subscribe to my free newsletter and get new articles by email.


  1. says

    I have found myself doing this for packages that have no upstream source. What is the best way to create packages when there is nothing to compile? You can hack the debian/rules file, but that is not newbie friendly.

    • says

      You can also say the same when the upstream source is ready to use (scripts that do not need to be compiled). So it’s not a problem limited to packages without upstream sources.

      Tweaking debian/rules is possible but nowadays you’re more likely to have a standard 3 lines debian/rules using dh and you would just tweak debian/install (used by dh_install) to tell where you have to copy the various files.

  2. says

    Compiling is only a small part of package building. Even for non-compiled stuff, like pure data packages, a proper ./debian sub-directory and “dpkg-buildpackage” or “debuild” are recommended.

  3. says

    Meh no, I won’t do that, didn’t even get the idea (dh_make gave me a good template for compat=4 which, with compat=5, I still use). But I thought, let me share this, to make you run away crying (only needed to build KDE 3 kdepim on KDE 4 / squeeze); note to all other readers, DO NOT even THINK of doing this ☺:

    $ echo ======================== | cat debian/control - debian/rules                                         
    Source: kdebase-kio-plugins
    Section: kde
    Priority: extra
    Maintainer: […]
    Build-Depends: binutils, ed
    # well, not really… Policy conformant…
    Standards-Version: 3.9.1
    Package: kde3base-kio-plugins
    Architecture: i386
    Description: KDE 3 KIO slaves
     This package is generated from the .deb from Lenny.
    #!/usr/bin/make -f
            -rm -rf builddir debian/files
            -rm -rf builddir
            mkdir builddir
            t=$$(pwd); for arch in ${ARCHES}; do \
                    cd builddir; \
                    rm -rf control* data* debian*; \
                    ar x ../kdebase-kio-plugins_${VSN}_$${arch}.deb; \
                    mkdir control data; \
                    cd control; \
                    tar xzpf ../control.tar.gz; \
                    ed -s control ../control.tar.gz; \
                    cd ../data; \
                    tar xzpf ../data.tar.gz; \
                    mv usr/share/doc/kdebase-kio-plugins \
                        usr/share/doc/kde3base-kio-plugins; \
                    mv usr/share/doc/kde/HTML \
                        usr/share/doc/kde3base-kio-plugins/HTML; \
                    rm -rf usr/bin/ktrash usr/share/apps/konqueror \
                        usr/share/apps/remoteview usr/share/apps/systemview \
                        usr/share/config.kcfg usr/share/man/man1/ktrash.1.gz \
                        usr/share/doc/kde; \
                    tar cf - . | gzip -n9 >../data.tar.gz; \
                    cd ..; \
                    ar rc ../../kde3base-kio-plugins_${VSN}_$${arch}.deb \
                        debian-binary control.tar.gz data.tar.gz; \
                    cd ..; \
                    dpkg-distaddfile kde3base-kio-plugins_${VSN}_$${arch}.deb \
                        kde extra; \
            -rm -rf builddir
    binary: binary-indep binary-arch
    .PHONY: build clean binary-indep binary-arch binary install check
  4. says

    I have had a riddiculous time trying to read how to make a blasted .deb from my own Qt projects and I just couldn’t figure it out. I think I gave up at the rules section where it expected me to know how to do a makefile from scratch or use autotools or something.

    So I did the easiest thing, extract contents of another package, edit the debian files and fakeroot directory, and use dpkg -b. Maybe if the documentation were easier written. Once I figure it out, I’ll surely put it up on my blog and probably the Ubuntu wiki, sure.

  5. says

    Oddly enough I’ve had reason to use dpkg -b today. I tweaked the dependencies for the proprietary dropbox tool, to remove an epoch on libnautilus-extension1. They target Ubuntu, who must have cocked up at some point and had to epoch their package, but Debian hasn’t.

  6. Luke says

    Thanks for this article. There are many tools. It’s not always obvious which ones to choose without a lot of trying things and a few false starts. For example, a while ago we needed to make a convenient way for our other developers to make debs without having to learn all about it. After reading about many tools listed here and in the New Maintainers Guide (and googling), it was still hard to see which were a fit for us, because some of the workflows just didn’t match what we needed to do, or were confusing (assumed confusing prior knowledge, like debhelper did, where the prior knowledge wasn’t very applicable outside a particular workflow). I think we finally went with dpkg-deb because it just made sense and was clean and clear, before we switched to jdeb for various project-specific reasons (packaging java projects from java projects on both linux and windows, to run on debian).

    One suggestion might be to somewhere list all the tools, each one with their conceptual inputs and key outputs, how they relate to each other, and when each one makes sense or doesn’t. Otherwise, for me at least, dpkg-buildpackage, debuild, dh, debhelper, dh_make, and whatever else they refer to were a lot to wade through when what we really needed were dpkg, aptitude, dpkg-deb, and jdeb, plus the FHS documents and the (always useful) Debian Policy.

    To be clear: I’m a big debian fan since I first tried linux in 1998, and a fan of the great folks who make it work so well. Where I work we make a lot of debs now (and rpms, but that’s another story, where we use yum, rpm and a modified redline library).

    • says

      I’m increasingly of the opinion that a bottom-up guide to the composition of Debian packages might be a better way of educating people than the current top-down approach in maint-guide which, as you point out, leaves you wondering what you don’t know. This seems to have worked well (for some value of ‘well’) for git, where I found the bottom-up guide “Git for Computer Scientists” left me feeling a lot more confident than the myriad attempts at explaining it from a top-down, or compared-to-another-vcs perspective.

      I might try and write a concise bottom-up guide to Debian packages and see how clear it appears. I happen to have some technically proficient folks that do not currently know anything about .debs that I could try a dry-run on.