Debian Policy Manual

This manual describes the policy requirements for the Debian distribution. This includes the structure and contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution.

This is Debian Policy version 4.7.0.1, released on 2024-08-25.

• 1. About this manual
  • 1.1. Scope
  • 1.2. New versions of this document
  • 1.3. Authors and Maintainers
    • 1.3.1. Early history
    • 1.3.2. Current process
    • 1.3.3. Improvements
  • 1.4. Related documents
  • 1.5. Definitions
  • 1.6. Translations
• 2. The Debian Archive
  • 2.1. The Debian Free Software Guidelines
  • 2.2. Archive areas
    • 2.2.1. The main archive area
    • 2.2.2. The non-free-firmware archive area
    • 2.2.3. The contrib archive area
    • 2.2.4. The non-free archive area
  • 2.3. Copyright considerations
  • 2.4. Sections
  • 2.5. Priorities
• 3. Binary packages
  • 3.1. The package name
    • 3.1.1. Packages with potentially offensive content
  • 3.2. The version of a package
    • 3.2.1. Version numbers based on dates
    • 3.2.2. Uniqueness of version numbers
  • 3.3. The maintainer of a package
  • 3.4. The description of a package
    • 3.4.1. The single line synopsis
    • 3.4.2. The extended description
  • 3.5. Dependencies
  • 3.6. Virtual packages
  • 3.7. Base system
  • 3.8. Essential packages
  • 3.9. Maintainer Scripts
    • 3.9.1. Prompting in maintainer scripts
• 4. Source packages
  • 4.1. Standards conformance
  • 4.2. Package relationships
  • 4.3. Changes to the upstream sources
  • 4.4. Debian changelog: debian/changelog
  • 4.5. Copyright: debian/copyright
  • 4.6. Error trapping in makefiles
  • 4.7. Time Stamps
  • 4.8. Restrictions on objects in source packages
  • 4.9. Main building script: debian/rules
    • 4.9.1. debian/rules and DEB_BUILD_OPTIONS
    • 4.9.2. debian/rules and Rules-Requires-Root
  • 4.10. Variable substitutions: debian/substvars
  • 4.11. Upstream source location: debian/watch
  • 4.12. Generated files list: debian/files
  • 4.13. Embedded code copies
  • 4.14. Source package handling: debian/README.source
  • 4.15. Reproducibility
  • 4.16. Missing sources: debian/missing-sources
  • 4.17. Vendor-specific patch series
• 5. Control files and their fields
  • 5.1. Syntax of control files
  • 5.2. Debian source package template control files – debian/control
  • 5.3. Debian binary package control files – DEBIAN/control
  • 5.4. Debian source package control files – .dsc
  • 5.5. Debian upload changes control files – .changes
  • 5.6. List of fields
    • 5.6.1. Source
    • 5.6.2. Maintainer
    • 5.6.3. Uploaders
    • 5.6.4. Changed-By
    • 5.6.5. Section
    • 5.6.6. Priority
    • 5.6.7. Package
    • 5.6.8. Architecture
    • 5.6.9. Essential
    • 5.6.10. Package interrelationship fields: Depends, Pre-Depends, Recommends, Suggests, Breaks, Conflicts, Provides, Replaces, Enhances
    • 5.6.11. Standards-Version
    • 5.6.12. Version
      • 5.6.12.1. Epochs should be used sparingly
      • 5.6.12.2. Special version conventions
    • 5.6.13. Description
    • 5.6.14. Distribution
    • 5.6.15. Date
    • 5.6.16. Format
    • 5.6.17. Urgency
    • 5.6.18. Changes
    • 5.6.19. Binary
    • 5.6.20. Installed-Size
    • 5.6.21. Files
    • 5.6.22. Closes
    • 5.6.23. Homepage
    • 5.6.24. Checksums-Sha1 and Checksums-Sha256
    • 5.6.25. DM-Upload-Allowed
    • 5.6.26. Version Control System (VCS) fields
    • 5.6.27. Package-List
    • 5.6.28. Package-Type
    • 5.6.29. Dgit
    • 5.6.30. Testsuite
    • 5.6.31. Rules-Requires-Root
      • 5.6.31.1. Remarks
      • 5.6.31.2. Definition of the keywords
      • 5.6.31.3. Provided keywords
  • 5.7. User-defined fields
  • 5.8. Obsolete fields
    • 5.8.1. DM-Upload-Allowed
• 6. Package maintainer scripts and installation procedure
  • 6.1. Introduction to package maintainer scripts
  • 6.2. Maintainer scripts idempotency
  • 6.3. Controlling terminal for maintainer scripts
  • 6.4. Exit status
  • 6.5. Summary of ways maintainer scripts are called
  • 6.6. Details of unpack phase of installation or upgrade
  • 6.7. Details of configuration
  • 6.8. Details of removal and/or configuration purging
• 7. Declaring relationships between packages
  • 7.1. Syntax of relationship fields
  • 7.2. Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends
  • 7.3. Packages which break other packages - Breaks
  • 7.4. Conflicting binary packages - Conflicts
  • 7.5. Virtual packages - Provides
  • 7.6. Overwriting files and replacing packages - Replaces
    • 7.6.1. Overwriting files in other packages
    • 7.6.2. Replacing whole packages, forcing their removal
  • 7.7. Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Depends-Arch, Build-Conflicts, Build-Conflicts-Indep, Build-Conflicts-Arch
  • 7.8. Additional source packages used to build the binary - Built-Using
• 8. Shared libraries
  • 8.1. Run-time shared libraries
    • 8.1.1. ldconfig
  • 8.2. Shared library support files
  • 8.3. Static libraries
  • 8.4. Development files
  • 8.5. Dependencies between the packages of the same library
  • 8.6. Dependencies between the library and other packages
    • 8.6.1. Generating dependencies on shared libraries
    • 8.6.2. Shared library ABI changes
    • 8.6.3. The symbols system
      • 8.6.3.1. The symbols files present on the system
      • 8.6.3.2. The symbols File Format
      • 8.6.3.3. Providing a symbols file
    • 8.6.4. The shlibs system
      • 8.6.4.1. The shlibs files present on the system
      • 8.6.4.2. The shlibs File Format
      • 8.6.4.3. Providing a shlibs file
• 9. The Operating System
  • 9.1. File system hierarchy
    • 9.1.1. File System Structure
    • 9.1.2. Site-specific programs
    • 9.1.3. The system-wide mail directory
    • 9.1.4. /run and /run/lock
  • 9.2. Users and groups
    • 9.2.1. Introduction
    • 9.2.2. UID and GID classes
    • 9.2.3. Non-existent home directories
  • 9.3. Starting system services
    • 9.3.1. Introduction
    • 9.3.2. Writing the scripts
    • 9.3.3. Interfacing with init systems
      • 9.3.3.1. Managing the links
      • 9.3.3.2. Running init scripts
    • 9.3.4. Boot-time initialization
    • 9.3.5. Example
  • 9.4. Console messages from init.d scripts
  • 9.5. Cron jobs
    • 9.5.1. Cron job file names
  • 9.6. Menus
  • 9.7. Multimedia handlers
    • 9.7.1. Registration of media type handlers with desktop entries
    • 9.7.2. Registration of media type handlers with mailcap entries
    • 9.7.3. Providing media types to files
  • 9.8. Keyboard configuration
  • 9.9. Environment variables
  • 9.10. Registering Documents using doc-base
  • 9.11. Alternate init systems
    • 9.11.1. Event-based boot with upstart
  • 9.12. Signaling that a reboot is required
• 10. Files
  • 10.1. Binaries
  • 10.2. Libraries
  • 10.3. Shared libraries
  • 10.4. Scripts
  • 10.5. Symbolic links
  • 10.6. Device files
  • 10.7. Configuration files
    • 10.7.1. Definitions
    • 10.7.2. Location
    • 10.7.3. Behavior
    • 10.7.4. Sharing configuration files
    • 10.7.5. User configuration files (“dotfiles”)
  • 10.8. Log files
  • 10.9. Permissions and owners
    • 10.9.1. The use of dpkg-statoverride
  • 10.10. File names
• 11. Customized programs
  • 11.1. Architecture specification strings
    • 11.1.1. Architecture wildcards
  • 11.2. Daemons
  • 11.3. Using pseudo-ttys and modifying wtmp, utmp and lastlog
  • 11.4. Editors and pagers
  • 11.5. Web servers and applications
  • 11.6. Mail transport, delivery and user agents
  • 11.7. News system configuration
  • 11.8. Programs for the X Window System
    • 11.8.1. Providing X support and package priorities
    • 11.8.2. Packages providing an X server
    • 11.8.3. Packages providing a terminal emulator
    • 11.8.4. Packages providing a window manager
    • 11.8.5. Packages providing fonts
    • 11.8.6. Application defaults files
    • 11.8.7. Installation directory issues
  • 11.9. Perl programs and modules
  • 11.10. Emacs lisp programs
  • 11.11. Games
• 12. Documentation
  • 12.1. Manual pages
  • 12.2. Info documents
  • 12.3. Additional documentation
  • 12.4. Preferred documentation formats
  • 12.5. Copyright information
    • 12.5.1. Machine-readable copyright information
  • 12.6. Examples
  • 12.7. Changelog files and release notes

Appendices

• 1. Introduction and scope of these appendices
• 2. Binary packages (from old Packaging Manual)
  • 2.1. Creating package files - dpkg-deb
  • 2.2. Binary package metadata files
  • 2.3. The binary package control file: control
  • 2.4. Time Stamps
• 3. Source packages (from old Packaging Manual)
  • 3.1. Tools for processing source packages
    • 3.1.1. dpkg-source - packs and unpacks Debian source packages
    • 3.1.2. dpkg-buildpackage - overall package-building control script
    • 3.1.3. dpkg-gencontrol - generates binary package control files
    • 3.1.4. dpkg-shlibdeps - calculates shared library dependencies
    • 3.1.5. dpkg-distaddfile - adds a file to debian/files
    • 3.1.6. dpkg-genchanges - generates a .changes upload control file
    • 3.1.7. dpkg-parsechangelog - produces parsed representation of a changelog
    • 3.1.8. dpkg-architecture - information about the build and host system
  • 3.2. The Debian package source tree
    • 3.2.1. debian/rules - the main building script
    • 3.2.2. debian/substvars and variable substitutions
    • 3.2.3. debian/files
    • 3.2.4. debian/tmp
  • 3.3. Source packages as archives
  • 3.4. Unpacking a Debian source package without dpkg-source
    • 3.4.1. Restrictions on objects in source packages
• 4. Control files and their fields (from old Packaging Manual)
  • 4.1. Syntax of control files
  • 4.2. List of fields
    • 4.2.1. Filename and MSDOS-Filename
    • 4.2.2. Size and MD5sum
    • 4.2.3. Status
    • 4.2.4. Config-Version
    • 4.2.5. Conffiles
    • 4.2.6. Obsolete fields
• 5. Configuration file handling (from old Packaging Manual)
  • 5.1. Automatic handling of configuration files by dpkg
  • 5.2. Fully-featured maintainer script configuration handling
• 6. Alternative versions of an interface - update-alternatives (from old Packaging Manual)
• 7. Diversions - overriding a package’s version of a file (from old Packaging Manual)
• 8. Debian Policy changes process
  • 8.1. Introduction
  • 8.2. Change Goals
  • 8.3. Current Process
    • 8.3.1. State A: More information required
    • 8.3.2. State B: Discussion
    • 8.3.3. State C: Proposal
    • 8.3.4. State D: Wording proposed
    • 8.3.5. State E: Seconded
    • 8.3.6. State F: Accepted
    • 8.3.7. State G: Reject
  • 8.4. Other Tags
• 9. Maintainer script flowcharts
• 10. Upgrading checklist
  • 10.1. About the checklist
  • 10.2. Version 4.7.0
  • 10.3. Version 4.6.2
  • 10.4. Version 4.6.1
  • 10.5. Version 4.6.0
  • 10.6. Version 4.5.1
  • 10.7. Version 4.5.0
  • 10.8. Version 4.4.1
  • 10.9. Version 4.4.0
  • 10.10. Version 4.3.0
  • 10.11. Version 4.2.1
  • 10.12. Version 4.2.0
  • 10.13. Version 4.1.5
  • 10.14. Version 4.1.4
  • 10.15. Version 4.1.3
  • 10.16. Version 4.1.2
  • 10.17. Version 4.1.1
  • 10.18. Version 4.1.0
  • 10.19. Version 4.0.1
  • 10.20. Version 4.0.0
  • 10.21. Version 3.9.8
  • 10.22. Version 3.9.7
  • 10.23. Version 3.9.6
  • 10.24. Version 3.9.5
  • 10.25. Version 3.9.4
  • 10.26. Version 3.9.3
  • 10.27. Version 3.9.2
  • 10.28. Version 3.9.1
  • 10.29. Version 3.9.0
  • 10.30. Version 3.8.4
  • 10.31. Version 3.8.3
  • 10.32. Version 3.8.2
  • 10.33. Version 3.8.1
  • 10.34. Version 3.8.0
  • 10.35. Version 3.7.3
  • 10.36. Version 3.7.2.2
  • 10.37. Version 3.7.2
  • 10.38. Version 3.7.1
  • 10.39. Version 3.7.0
  • 10.40. Version 3.6.2
  • 10.41. Version 3.6.1
  • 10.42. Version 3.6.0
  • 10.43. Version 3.5.10
  • 10.44. Version 3.5.9
  • 10.45. Version 3.5.8
  • 10.46. Version 3.5.7
  • 10.47. Version 3.5.6
  • 10.48. Version 3.5.5
  • 10.49. Version 3.5.4
  • 10.50. Version 3.5.3
  • 10.51. Version 3.5.2
  • 10.52. Version 3.5.1
  • 10.53. Version 3.5.0
  • 10.54. Version 3.2.1.1
  • 10.55. Version 3.2.1
  • 10.56. Version 3.2.0
  • 10.57. Version 3.1.1
  • 10.58. Version 3.1.0
  • 10.59. Version 3.0.1
  • 10.60. Version 3.0.0
  • 10.61. Version 2.5.0
  • 10.62. Version 2.4.1
  • 10.63. Version 2.4.0
  • 10.64. Version 2.3.0
  • 10.65. Version 2.2.0
  • 10.66. Version 2.1.3
  • 10.67. Version 2.1.2
  • 10.68. Version 2.1.1
  • 10.69. Version 2.1.0
• 11. License