The Packaging and Development guide is currently undergoing a major overhaul to bring it up to date. The current state you are seeing now is a preview of this effort.
The current version is unstable (changing URLs can occur at any time) and most content is not in properly reviewed yet. Proceed with caution and be aware of technical inaccuracies.
If you are an experienced packager and would like to contribute, we would love for you to be involved! See our contribution page for details of how to join in.
A source package contains the source material used to build one or more binary packages.
A source package is composed of:
a Debian Source Control (
one or more compressed tar files, and
optionally additional files depending on the type and format of the source package.
The Source Control file contains metadata about the source package, for instance, a list of additional files, name and version, list of the binary packages it produces, dependencies, a digital signature and many more fields.
The basic overview of the debian/ directory article showcases the layout of an unpacked source package.
Source package formats¶
There are multiple formats for how the source is packaged. The format of a
source package is declared in the
debian/source/format file. This file
should always exist. If this file can not be found, the format 1.0
is assumed for backwards compatibility, but lintian(1) will warn you
about it when you try to build a source package.
We strongly recommend to use the 3.0 (quilt) format for new packages.
You should only pick a different format if you really know what you are doing.
Native source packages¶
In most cases, a software project is packaged by external contributors called the maintainers of the package. Because the packaging is often done by a 3rd-party (from the perspective of the software project), the software to be packaged is often not designed to be packaged. In these cases the source package has to do modifications to solve specific problems for its target distribution. The source package can, in these cases, be considered as its own software project, like a fork. Consequently, the Upstream releases and source package releases do not always align.
Native packages almost always originate from software projects designed with Debian packaging in mind and have no independent existence outside its target distribution. Consequently native packages do not differentiate between Upstream releases and source package releases. Therefore, the version identifier of a native package does not have an Debian-specific component.
The debhelper package (provides tools for building Debian packages) is a native package from Debian. Because it is designed with packaging in mind, the packaging specific files are part of the original source code. The debhelper developers are also maintainers of the Debian package. The Debian debhelper package gets merged into the Ubuntu debhelper package and has therefore a
ubuntusuffix in the version identifier.
In contrast, the Ubuntu bash package (the default shell on Ubuntu) is NOT a native package. The bash Software originates from the GNU project. The bash releases of the GNU project project will get packaged by Debian maintainers and the Debian bash package is merged into the Ubuntu bash package by Ubuntu maintainers. The Debian and Ubuntu packages both are effectively their own separate software projects maintained by other people than the developers of the software that gets packaged. This is the process how most software is packaged on Ubuntu.
Although native packages sound like the solution to use for your software project if you want to distribute your software to Ubuntu/Debian, we strongly recommend against using native package formats for new packages. Native packages are known to cause long-term maintenance problems.
A new-generation source package format that records modifications in a
quilt(1) Patch series within the
folder. The patches are organised as a stack, and you can apply,
unapply, and update them easily by traversing the stack (push/pop). These
changes are automatically applied during the extraction of the source package.
A source package in this format contains at least an original tarball
ext can be
and a debian tarball (
.debian.tar.ext). It can also contain additional
original tarballs (
component can only
contain alphanumeric (
0-9) characters and hyphens (
Optionally, each original tarball can be accompanied by a
detached signature from the upstream project
For example, take a look at the
pull-lp-source --download-only 'hello' '2.10-3'
You need to install
ubuntu-dev-tools to run the pull-lp-source:
sudo apt install ubuntu-dev-tools
When you now run ls(1):
ls -1 debhelper_*
you should see the following files:
hello_2.10-3.dsc: The Debian Source Control file of the source package.
hello_2.10.orig.tar.gz: The tarball containing the original source code of the upstream project.
hello_2.10.orig.tar.gz.asc: The detached upstream signature of
hello_2.10-3.debian.tar.xz: The tarball containing the content of the Debian directory.
A new-generation source package format extends the native package format defined in the format 1.0.
A source package in this format is a tarball (
For example, let’s take a look at the
pull-lp-source --download-only 'debhelper' '13.11.6ubuntu1'
When you now run ls(1):
ls -1 debhelper_*
you should see the following files:
debhelper_13.11.6ubuntu1.dsc: The Debian Source Control file of the source package.
debhelper_13.11.6ubuntu1.tar.xz: The tarball containing the source code of the project.
Other examples of native source packages are:
The original source package format. Nowadays, this format is rarely used.
A native source package in this format consists of a single
file containing the source.
A non-native source package in this format consists of a
(containing the Upstream source) associated with a
.diff.gz file (the patch
containing Debian packaging modifications). Optionally, the original tarball
can be accompanied by a detached Upstream signature
This format does not specify a patch system, which makes it harder for
maintainers to track modifications. There were multiple
approaches to how packages tracked patches. Therefore, the source packages of
this format often contained a
debian/README.source file explaining
how to use the patch system.
3.0 formats improvements¶
Some of the improvements that apply to most
3.0 formats are:
Support for additional compression formats:
Support for multiple Upstream tarballs.
Supports inclusion of binary files.
Debian-specific changes are no longer stored in a single
The Upstream tarball does not need to be repacked to strip the Debian directory.
The following formats are rarely used, experimental and/or historical. You should only choose these if you know what you are doing.
3.0 (custom): Doesn’t represent an actual source package format but can be used to create source packages with arbitrary files.
3.0 (git): An experimental format to package from a git repository.
3.0 (bzr): An experimental format to package from a Bazaar repository.
2.0: The first specification of a new-generation source package format. It was never widely adopted and eventually replaced by 3.0 (quilt).
Although technically not part of a source package – every time a source package
is built, a
.changes file will be created alongside it. The
file contains metadata from the Source Control file and other information (e.g.
the latest changelog entry) about the source package. Archive tools and
Archive Administrators use this data to process changes
to source packages and determine the appropriate action to upload the source
package to the Ubuntu Archive.
A binary package is a standardised format that the Package Manager (dpkg(1) or apt(8)) can understand to install and uninstall software on a target machine. This simplifies distributing software to a target machine and managing the software on that machine.
A Debian binary package uses the
.deb file extension and contains a set
of files that will be installed on the host system and a set of files that
control how the files will be installed or uninstalled.