Usage

Basic Commands

Install (Default Command)

Install packages from an Aptfile:

# Use default Aptfile (./Aptfile)
sudo apt-bundle

# Or explicitly
sudo apt-bundle install

# Use a different Aptfile
sudo apt-bundle --file /path/to/Aptfile
sudo apt-bundle install --file /path/to/Aptfile

The install command:

  1. Adds all specified repositories and GPG keys
  2. Runs apt-get update (by default, can be skipped with --no-update)
  3. Installs all specified packages

Note: The install command requires root privileges (use sudo).

Check

Check if packages and repositories from the Aptfile are installed (no root required):

# Check using default Aptfile
apt-bundle check

# Check using a different file
apt-bundle check --file /path/to/Aptfile

This command reads the Aptfile and reports which packages/repositories are missing or not installed, without actually installing them.

Dump

Generate an Aptfile from the system’s current state:

# Output to stdout
apt-bundle dump

# Save to file
apt-bundle dump > Aptfile

This command outputs a list of manually installed packages. Future versions may also include custom PPAs and deb repositories.

Command-Line Options

Global Flags

Install Command Flags

Examples

Basic Package Installation

Create an Aptfile:

apt vim
apt curl
apt git
apt build-essential

Install:

sudo apt-bundle

Using a Custom Aptfile Location

sudo apt-bundle --file /etc/myproject/Aptfile

Skipping Package List Update

If your package lists are already up-to-date (e.g., in CI/CD where you’ve already run apt-get update):

sudo apt-bundle --no-update

Checking Before Installing

# Check what's missing
apt-bundle check

# Review the output, then install
sudo apt-bundle

Generating an Aptfile

# On your primary workstation
apt-bundle dump > Aptfile

# Commit to version control
git add Aptfile
git commit -m "Add system dependencies"

# On a new machine
git clone <repo>
cd <repo>
sudo apt-bundle

Use Cases

Developer Onboarding

# Clone project
git clone https://github.com/myorg/myproject.git
cd myproject

# Install all system dependencies
sudo apt-bundle

Dockerfile

Use apt-bundle in your Dockerfiles to manage system dependencies declaratively. See the examples directory for complete working examples including multi-stage builds, Python runtimes, CI/CD setups, and more.

CI/CD with GitHub Actions

The apt-bundle/apt-bundle-action GitHub Action provides a streamlined integration with built-in package caching:

# .github/workflows/test.yml
- name: Install system dependencies
  uses: apt-bundle/apt-bundle-action@v1

To validate dependencies without installing (e.g. in a lint step):

- name: Check dependencies
  uses: apt-bundle/apt-bundle-action@v1
  with:
    mode: check

See the GitHub Actions page for the full reference.

System Sync

# On primary workstation
apt-bundle dump > ~/dotfiles/Aptfile

# On new laptop
cp ~/dotfiles/Aptfile .
sudo apt-bundle

Idempotency

All operations are idempotent, meaning you can safely run apt-bundle install multiple times:

This makes apt-bundle safe to run repeatedly, which is especially useful in CI/CD pipelines and Dockerfiles.

Error Handling

If apt-bundle encounters an error:

Common errors:

Next Steps