Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• Packaging

Translation(s): English - Español - Português (Brasil) - Italiano - Svenska - Русский

This is the packaging portal, for people who want to create new packages. For commonly-installed packages, see Software. Or to install and remove packages, see package management.

General guides

There are no shortcuts to learning good packaging practices - you can't just throw a trivial packager like equivs at the problem and hope for the best.

The links in this section will help you gain a deep understanding of the problems you need to solve if you want to create or maintain a package.

Find your feet

The first step is to find a basic approach that works for you. The Debian mentors FAQ advises you to re-consider, clarifies why and how to start, and provides a short overview of the process.

New tools are invented every few years, and the best way to use them depends on the specific projects you want to package and the way you like to work. Here are some guides you can get inspiration from:

• create a .deb for private use shows how to make a basic package in 5 minutes

• a tutorial series from 2010-2011 helps you learn the theory:

  • introduction to Debian packaging explains packaging from scratch

  • the building tutorial explains applying changes to an existing package

  • advanced building tips covers some details that didn't fit in the other tutorials

• a tutorial series from 2025 by Otto Kekäläinen shows one good packaging workflow:

  • Creating Debian packages from upstream Git

  • Debian source packages in git explained

• packaging with git discusses common git-based workflows

• the debconf developers guide explains how to ask the user questions during installation

• Guide for Debian Maintainers provides a reference for common tools discussed in tutorials

  • replaces the outdated Debian New Maintainers' Guide

Debian packaging works by example as much as by theory. Find well-maintained packages, and see how they do it!

Further reading

Once you've found a workflow you can live with, you can optimise it for your personal requirements. These pages might give you some ideas:

• learn Debian Packaging in steps takes you from new to advanced packaging levels (by the JavaScript team)

• Debian Packaging Tutorial tells you what you really need to know about Debian packaging

• The Developers Reference gives an overview of recommended procedures and available resources

• How will my package get into Debian? walks you through the process of getting packages accepted by Debian

• The packaging FAQ answers some common questions

• The upstream guide advises upstream maintainers how to support packaging

• Complex Web Apps discusses creating Debian packages for complex web applications

• setting up a Debian unstable system provides some options for creating a clean package-building environment

These advanced pages explain how packaging works under the hood:

• the Debian Policy - technical requirements that each package must satisfy

• Projects/DebSrc3.0 - details about the "3.0 (quilt)" and "3.0 (native)" source package formats

• Courses2005/BuildingWithoutHelper - how to make a Debian package without using a helper

• /HackingDependencies - hacking dependencies

• Diagrams - packaging-related diagrams and sketches

• Debian Trends - how packaging practices have evolved over time

Finally, if you'd like to see the development process for the packaging system itself:

• PackageConfigUpgrade - proposed way to smoothly handle configuration upgrades during package upgrades

• DataPackages - brainstorming about huge data packages

More granular guides

Once you're comfortable creating packages generally, you'll need to learn the tools and techniques for your particular problem.

Language-specific guides

Each of Debian's language-specific teams have their own policies and tools:

• Emacs Lisp team page

• Golang packaging documentation

• Haskell team page

• Java packaging guide

  • see also Guidelines for Packages Maintained on salsa.debian.org/java-team

• JavaScript policy

  • Node.js packaging guide

• Lua group page

• Mono packaging guide

• OCaml maintainers page

• Perl packaging guide

• Python library style guide

• Ruby packaging guide

• Rust team page

see also a comparison of tools that create Debian packages

Topic-specific guides

If your package addresses a specific topic, you may need to read information from people who have been there before:

• Android tools information

• Debian team guides

  • Debian GNOME Team guide

  • KDE Team home page

  • Debian MATE Packaging Team guide

  • Debian Med team policy

  • Debian Multimedia packaging guide

  • Vim team packaging guide

  • Debian Science policy manual

  • other packaging teams may have guides

• fonts packaging policy

• repackaging RPM source packages as .deb packages

  • see also using RPM in Debian

Tool guides

You will probably need to use some of these:

• pbuilder or sbuild to create environments to build packages in

• lintian, piuparts, autopkgtest and blhc to debug your packages

You might also want to use some of these:

• Packaging/ruby-team-meta-build - build scripts used by ruby team, helps testing reverse dependencies easily

• Quilt for managing patches without a version control system

• devscripts to make your life easier

• dh-make to convert source archives into Debian package source

• checkinstall lets you build binary .deb packages from installation scripts (make install...)

Job guides

If you're trying to achieve a particular outcome:

• rename a package

• transition users from one package to another

• let files from one package be temporarily replaced by files from another

• make a package for your config files

• make a private backport from unstable to stable

• make a backport suitable for backports.debian.org

• create a package from an Ubuntu PPA

• upload source packages without binary packages

  • see also Debian archive

• avoid keeping convenience copies of files from one project in another

• language-specific solutions for versioned -dev packages

• write a good package description

• manage differences between your package and upstream

File guides

If you need help with a particular file in your package's debian/ directory:

• debian/changelog - changes between versions of your package

• debian/copyright - copyright information about the upstream package

• debian/patches - debian-specific patches to the upstream code

• debian/upstream - files describing the upstream project

  • debian/upstream/edam - formal categorisation from the EDAM ontology

  • debian/upstream/metadata - miscellaneous information

• debian/watch - check for upstream updates

To find real-world examples of any debian/ file, go to codesearch.debian.net and search for e.g. Reference path:debian/control.

Working with other developers

If you want to get involved with the Debian community:

• Mentors - sponsors/mentors for packages in specific areas of Debian

  • introduction for reviewers

• SponsorChecklist - Sponsor Checklist

• Software that can't be packaged - projects that have already been found ineligible for inclusion in Debian

• guidelines for processing the NEW queue

  • LucaFalavigna's checklist

  • Reject FAQ

• DEX - improving Debian and its derivatives through cross-community teamwork

• how developers can help packagers

• Work-Needing and Prospective Packages - packages that have been requested for packaging, or need a new maintainer

• Salsa - GitLab-based Debian development server

Training Sessions

DebianWomen organise training sessions.

External links

• What's in a debian/ directory

• Managing Debian package files with cme

• Ubuntu Packaging Guide

• Debian Binary Package Building HOWTO (2005)

• How to build and deploy a Debian Package with GitLab CI

• fpm can build .deb packages from various other package formats (rubygems, pip, pear, tar, npm, pacman...)

• Packaging - Ubuntu Wiki

• Debian build tools - Russ's Debian Notes

• Packaging Scripts for Debian - Russ's Debian Notes

See also

• Debian adminstration - Rolling your own Debian packages (part 1)

• Autobuilding non-free packages

• A Debian packaging howto (2010)

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

• Debuginfod eliminates the need for users to install debuginfo packages in order to debug programs using GDB, systemtap or other tools

• Browse through the source code of the Debian operating system

Wiki pages

All pages related to packaging in Debian:

CategoryPackaging | CategoryPortal