# Snapshots

Save the offline machine’s installed package list and apt settings so builds include what it needs.

Source: https://debark.dev/docs/concepts/snapshots

---
A snapshot is a compressed file describing a machine’s apt and dpkg state. Debark uses it to
work out which packages that machine needs.

You can also [build with a baseline OS](/docs/get-started/no-target-machine) without capturing
a snapshot. Choose that option for a stock installation; use a captured snapshot for the
actual state of a particular machine.

Take the snapshot on the offline machine. Creating it needs no internet or root access and
doesn’t change installed packages.

## Create and inspect a snapshot

```bash
debark snapshot create --out target.tar.zst
debark snapshot inspect target.tar.zst
```

Without `--out`, the filename is `snapshot.tar.zst`. Inspection shows the target release,
architecture, installed package count, and how the snapshot was created. Use `--json` for
structured output.

Copy the snapshot to the online computer and pass it to `debark build --snapshot`.

## What a snapshot holds

| Information                                  | Why the build needs it                                           |
| -------------------------------------------- | ---------------------------------------------------------------- |
| Installed packages and versions              | Avoid downloading dependencies already present on the target     |
| apt sources                                  | Download from the repositories configured for the target         |
| Version preferences and holds                | Respect the target’s package selection rules                     |
| apt settings                                 | Preserve choices such as whether to install recommended packages |
| Archive public keys                          | Check packages against the target’s configured archive keys      |
| Release, architecture, and apt/dpkg versions | Choose compatible packages and a build backend                   |
| Machine ID                                   | Apply Ubuntu’s phased-update policy for the target               |

It does not contain the installed .deb files, application data, or a backup of the machine.
Software managed outside apt and dpkg isn’t described.

## Redacting and labelling

Add labels to help identify snapshots:

```bash
debark snapshot create --out lab-server.tar.zst \
  --label machine=lab-server --label purpose=monthly-update
```

Use `--redact` when you need to remove the machine ID, proxy settings, and labels:

```bash
debark snapshot create --out target.tar.zst --redact
```

A redacted snapshot still contains package and repository information. Review it before sharing
it outside your usual working environment. Redaction also affects phased updates, described below.

## Captured or synthesized

**Captured** snapshots come from `snapshot create` on a real machine. Use this option whenever
you can access the target.

**Synthesized** snapshots describe an assumed stock Debian or Ubuntu installation. `build --base`
creates this description as part of a build; you do not need to supply a snapshot file.
`snapshot from-base` saves the same kind of description as a reusable file.

The `origin.kind` field records `captured` or `synthesized`; `snapshot inspect` shows it.

A base can assume packages are installed when the actual machine doesn’t have them, leaving
dependencies out of the bundle. Builds from bases have less testing than captured snapshots.
See [building without a snapshot](/docs/get-started/no-target-machine).

## Phased updates

Ubuntu may make an update available to only some machines during a gradual rollout. Debark uses
the target’s captured machine ID so apt can apply that policy to the target.

If the machine ID is absent, including after `--redact`, Debark excludes phased updates from
the automatic upgrade pass. Explicit package requests are handled separately.
This matters when using [`--upgrades`](/docs/guides/upgrades).

## Skipping the keyrings

`--no-keyrings` omits archive public keys and removes their `Signed-By` references from
the captured sources. Leave this flag off for normal use.

A snapshot without the key material cannot satisfy an `--approved-keys` check.
These archive keys are also separate from the operator key used to sign and verify the bundle.

## When to take a new snapshot

Capture again after installing or removing packages, changing apt sources or settings, or
changing the target’s architecture configuration. A build checks dependencies against the
snapshot, so an old snapshot may no longer describe what the machine needs.

<NextSteps
  items={[
    {
      title: 'Build a bundle',
      href: '/docs/guides/building-a-bundle',
      description: 'Use the snapshot to prepare downloads.',
    },
    {
      title: 'Build without a snapshot',
      href: '/docs/get-started/no-target-machine',
      description: 'Prepare for a stock Debian or Ubuntu system.',
    },
  ]}
/>