DEB Debian Package (.deb)

---
name: deb
description: "Create, inspect, and manage .deb packages for Debian-based systems when packaging software."
metadata:
  tags: "deb-packaging, debian, linux-packaging, dpkg, apt, package-management"
  source: "https://skilldb.dev/skills/file-formats-skills/deb"
  pack: "file-formats-skills"
  category: "Technology & Engineering"
---

# DEB Debian Package (.deb)

## When to use this skill
Use when the user says things like:
- "how do i create a deb package"
- "package my app as a deb for debian"
- "explain debian packaging with dpkg and apt"
- "build and distribute a .deb"
- "inspect a .deb file's contents"


You are a file format specialist with deep knowledge of the Debian package format, dpkg/APT package management, maintainer scripts, dependency resolution, and Debian packaging policy for creating and distributing software on Debian-based Linux systems.

## Overview

DEB is the software package format for Debian and its derivatives (Ubuntu, Linux Mint, Pop!_OS, Raspberry Pi OS, and hundreds more). A .deb file is an `ar` archive containing compiled binaries, configuration files, dependency information, and installation scripts. The `dpkg` tool handles low-level package operations, while APT (Advanced Package Tool) manages repositories, dependency resolution, and system-wide updates.

DEB packages are the foundation of software management on the world's most popular Linux distribution family.

## Technical Specifications

- **Extension:** `.deb`, `.udeb` (micro packages for Debian Installer)
- **MIME type:** `application/vnd.debian.binary-package`
- **Container:** `ar` archive containing three members
- **Compression:** gzip, xz, zstd, bzip2, or uncompressed (for data and control archives)
- **Architecture tags:** `amd64`, `i386`, `arm64`, `armhf`, `all` (arch-independent)

### Package Structure

```
package.deb (ar archive):
  ├── debian-binary           # Format version string: "2.0\
"
  ├── control.tar.xz          # Package metadata and scripts
  │   ├── control             # Package name, version, dependencies, description
  │   ├── md5sums             # Checksums of installed files
  │   ├── conffiles           # List of configuration files (preserved on upgrade)
  │   ├── preinst             # Pre-installation script
  │   ├── postinst            # Post-installation script
  │   ├── prerm               # Pre-removal script
  │   ├── postrm              # Post-removal script
  │   ├── triggers            # dpkg trigger definitions
  │   └── shlibs              # Shared library dependencies
  └── data.tar.xz             # Actual file contents
      ├── usr/
      │   ├── bin/myapp
      │   ├── lib/libmy.so.1
      │   └── share/
      │       ├── doc/myapp/
      │       ├── man/man1/myapp.1.gz
      │       └── applications/myapp.desktop
      └── etc/
          └── myapp/myapp.conf
```

### Control File Format

```
Package: myapp
Version: 1.2.3-1
Section: utils
Priority: optional
Architecture: amd64
Depends: libc6 (>= 2.31), libssl3 (>= 3.0.0), python3 (>= 3.10)
Recommends: myapp-plugins
Suggests: myapp-doc
Conflicts: oldapp
Replaces: oldapp
Installed-Size: 1024
Maintainer: Developer Name <dev@example.com>
Description: Short description of my application
 Long description of my application that explains
 what it does and why you might want it.
 .
 Second paragraph with more details.
Homepage: https://example.com/myapp
```

### Dependency Types

| Field | Meaning |
|-------|---------|
| `Depends` | Required to run (hard dependency) |
| `Pre-Depends` | Must be fully installed before unpacking |
| `Recommends` | Strongly suggested (installed by default in Ubuntu) |
| `Suggests` | Optional enhancements |
| `Conflicts` | Cannot be installed simultaneously |
| `Breaks` | Broken by this package version |
| `Replaces` | Files from this package replace another |
| `Provides` | Virtual package name this package fulfills |

## How to Work With It

### Installing

```bash
# Install a .deb file
sudo dpkg -i package.deb

# Install with automatic dependency resolution
sudo apt install ./package.deb     # note the ./ prefix

# Install from repository
sudo apt install package-name
sudo apt install package-name=1.2.3-1   # specific version

# Fix broken dependencies after dpkg install
sudo apt install -f
```

### Querying Packages

```bash
# List installed packages
dpkg -l | grep myapp
dpkg -l 'lib*'                     # glob pattern

# Show package info
dpkg -s myapp                      # installed package details
apt show myapp                     # repo package details

# List files in an installed package
dpkg -L myapp

# Find which package owns a file
dpkg -S /usr/bin/myapp

# List files in a .deb without installing
dpkg-deb -c package.deb

# Extract control info from .deb
dpkg-deb -I package.deb
dpkg-deb -e package.deb ./control-dir/
```

### Creating DEB Packages

```bash
# Method 1: dpkg-deb (simple, direct)
mkdir -p myapp_1.0-1_amd64/DEBIAN
mkdir -p myapp_1.0-1_amd64/usr/bin

# Create control file
cat > myapp_1.0-1_amd64/DEBIAN/control << 'EOF'
Package: myapp
Version: 1.0-1
Section: utils
Priority: optional
Architecture: amd64
Depends: libc6 (>= 2.31)
Maintainer: Dev <dev@example.com>
Description: My Application
 A useful application that does things.
EOF

# Add files
cp myapp myapp_1.0-1_amd64/usr/bin/
chmod 755 myapp_1.0-1_amd64/usr/bin/myapp

# Build
dpkg-deb --build myapp_1.0-1_amd64

# Method 2: debhelper (proper Debian packaging)
# Create debian/ directory with control, rules, changelog, etc.
debuild -us -uc                    # build without signing

# Method 3: fpm (multi-format packager)
fpm -s dir -t deb -n myapp -v 1.0 --prefix /usr/local ./build/
```

### Extracting Without Installing

```bash
# Extract data contents
dpkg-deb -x package.deb ./extracted/

# Extract everything (control + data)
ar x package.deb
tar xf control.tar.xz
tar xf data.tar.xz
```

## Common Use Cases

- **System software:** Kernel, init system, core utilities, shells
- **Desktop applications:** Firefox, LibreOffice, GIMP, VS Code
- **Server software:** nginx, PostgreSQL, Docker, Node.js
- **Libraries:** Shared libraries with proper versioning (`libfoo1`, `libfoo-dev`)
- **Development tools:** Compilers, build tools, language runtimes
- **Configuration packages:** System presets, customization bundles
- **Third-party software:** Vendor-provided .deb files (Google Chrome, Slack, Discord)

## Pros & Cons

### Pros
- Mature dependency resolution system (APT) prevents broken installations
- Maintainer scripts handle complex installation/removal procedures
- Configuration file management preserves user modifications on upgrade
- Extensive Debian/Ubuntu repository with 60,000+ packages
- Trigger system avoids redundant operations during batch installs
- Virtual packages enable flexible alternative dependency resolution
- Reproducible builds supported by Debian infrastructure
- `dpkg` is simple and reliable for low-level operations

### Cons
- Complex to create proper packages (debhelper, policy compliance)
- Dependency on system-wide library versions (not self-contained)
- Root privileges required for installation
- Cannot run multiple versions of the same package simultaneously
- Post-install scripts run as root (security concern for third-party debs)
- Repository management (GPG keys, sources.list) can be confusing
- No built-in sandboxing (Flatpak/Snap address this)

## Compatibility

| Distribution | Support | Notes |
|-------------|---------|-------|
| Debian | Native | Origin distribution |
| Ubuntu | Native | Most popular derivative |
| Linux Mint | Native | Based on Ubuntu |
| Pop!_OS | Native | System76's Ubuntu derivative |
| Raspberry Pi OS | Native | Based on Debian |
| elementaryOS | Native | Based on Ubuntu |
| Kali Linux | Native | Based on Debian |
| Chrome OS (Crostini) | Yes | Linux container uses Debian |

**Tools:** `dpkg`, `apt`/`apt-get`/`apt-cache`, `aptitude`, `synaptic` (GUI), `debuild`, `lintian` (policy checker), `reprepro`/`aptly` (repository management).

## Practical Usage

### Build a complete .deb package with fpm (quick method)

```bash
# Install fpm
sudo apt install ruby ruby-dev build-essential
sudo gem install fpm

# Package a Go/Rust/C binary into a .deb
fpm -s dir -t deb \
    -n myapp \
    -v 2.1.0 \
    --description "My application description" \
    --maintainer "Dev Name <dev@example.com>" \
    --url "https://example.com/myapp" \
    --license "MIT" \
    --depends "libc6 (>= 2.31)" \
    --after-install scripts/postinst.sh \
    --config-files /etc/myapp/config.toml \
    ./build/myapp=/usr/bin/myapp \
    ./config.toml=/etc/myapp/config.toml \
    ./myapp.service=/lib/systemd/system/myapp.service
```

### Inspect and audit a third-party .deb before installing

```bash
# View package metadata
dpkg-deb -I suspicious-package.deb

# List all files that would be installed
dpkg-deb -c suspicious-package.deb

# Extract without installing to inspect contents
mkdir /tmp/deb-audit && dpkg-deb -x suspicious-package.deb /tmp/deb-audit/
dpkg-deb -e suspicious-package.deb /tmp/deb-audit/DEBIAN/

# Review maintainer scripts (these run as root!)
cat /tmp/deb-audit/DEBIAN/postinst
cat /tmp/deb-audit/DEBIAN/prerm

# Check for files installed outside standard paths
find /tmp/deb-audit -not -path '*/DEBIAN/*' | sort
```

### Set up a local APT repository with reprepro

```bash
# Create repository structure
mkdir -p /srv/apt-repo/conf
cat > /srv/apt-repo/conf/distributions << 'EOF'
Origin: MyOrg
Label: MyOrg Internal Repo
Suite: stable
Codename: jammy
Architectures: amd64 arm64
Components: main
Description: Internal package repository
SignWith: default
EOF

# Add packages to the repository
reprepro -b /srv/apt-repo includedeb jammy myapp_2.1.0_amd64.deb

# Serve with nginx and add to clients:
# echo "deb [signed-by=/usr/share/keyrings/myorg.gpg] http://repo.example.com/apt jammy main" \
#   | sudo tee /etc/apt/sources.list.d/myorg.list
```

## Anti-Patterns

**Running `dpkg -i` without resolving dependencies first.** Using `dpkg -i package.deb` alone does not install dependencies, leaving the system in a broken state. Use `sudo apt install ./package.deb` instead, which resolves and installs dependencies automatically. If you must use dpkg, follow up immediately with `sudo apt install -f`.

**Putting user-modifiable configuration files outside /etc or not listing them in conffiles.** Configuration files not listed in the `conffiles` control file will be silently overwritten on package upgrade, destroying user customizations. Always place configuration in `/etc/` and list each config file path in `DEBIAN/conffiles`.

**Using maintainer scripts (postinst/prerm) for tasks that should be handled by triggers or declarative mechanisms.** Writing complex shell scripts in postinst that call `ldconfig`, `update-mime-database`, or `update-desktop-database` is fragile and runs redundantly during batch installs. Use dpkg triggers so these operations run once after all packages are configured.

**Installing files to /usr/local or /opt in distribution packages.** The `/usr/local` hierarchy is reserved for locally compiled software and `/opt` for self-contained third-party bundles. Distribution .deb packages should install to `/usr/bin`, `/usr/lib`, `/usr/share`, etc. following the Filesystem Hierarchy Standard.

**Hardcoding library paths or versions instead of using proper dependency declarations.** Bundling shared libraries inside the package or hardcoding `libfoo.so.3` paths instead of declaring `Depends: libfoo3 (>= 3.0)` breaks the system's dependency tracking, prevents security updates, and causes conflicts with other packages.

## Related Formats

- **RPM** — Red Hat's equivalent package format
- **Snap** — Canonical's universal sandboxed package format
- **Flatpak** — Desktop application sandboxed distribution
- **AppImage** — Portable, no-install Linux application format
- **ar** — Unix archive format (DEB container)
- **ipk** — OpenWrt package format (lightweight DEB derivative)