# Prepare package updates

Download upgrades for installed packages and choose when to apply them on the offline machine.

Source: https://debark.dev/docs/guides/upgrades

---
Updating an offline machine has two steps: download the newer package files online, then apply
them on the offline machine. These steps use different flags.

## Choose the right flags

| Flag         | Command   | Purpose                                                                   |
| ------------ | --------- | ------------------------------------------------------------------------- |
| `--upgrades` | `build`   | Include pending upgrades for packages already installed on the target     |
| `--update`   | `build`   | Refresh indexes and package selection, then prune superseded bundle files |
| `--upgrade`  | `install` | Also apply the upgrade set recorded in the bundle                         |

`--update` does not imply `--upgrades`. Use both when refreshing a bundle that should
also contain the target’s pending upgrades.

## Take a fresh snapshot

On the offline machine:

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

Copy the snapshot to the online computer. This makes the upgrade selection reflect the
machine’s current installed packages and apt settings.

## Download the updates

On the online computer:

```bash
debark build --snapshot target.tar.zst --out ./bundle \
  --sign operator.key --update --upgrades jq
```

This includes the requested package and the upgrades apt selects for the target.
An older system may need a large download. Check the summary with:

```bash
debark inspect ./bundle
debark doctor ./bundle
```

The build only prepares files. It does not change the offline machine.

## Preview and apply on the target

Copy the bundle to the offline machine. Use the trusted public key already stored there.

```bash
debark install ./bundle --key operator.pub --status
sudo debark install ./bundle --key operator.pub --upgrade --dry-run
```

Review the package list and any removals or warnings. Then apply the updates:

```bash
sudo debark install ./bundle --key operator.pub --upgrade
```

Without `--upgrade`, a normal install adds missing packages and leaves installed packages
at their current versions. Having newer .deb files in the bundle does not apply them automatically.

## Ubuntu phased updates

Ubuntu sometimes releases an update gradually. Debark uses the snapshot’s machine ID so apt
can apply the target’s phased-update policy. Without that ID, including in a redacted snapshot,
the automatic upgrade pass excludes phased updates.

An explicitly requested package can be selected outside that automatic upgrade pass.
See [snapshots](/docs/concepts/snapshots#phased-updates).

## Keep the bundle manageable

`--update` removes superseded files subject to the build’s pruning rules.
`--no-prune` keeps them. Packages removed from the request can also leave unused files in
an existing bundle directory.

Build into a fresh output directory if you want only the current result. Cached downloads are
still reused. See [refreshing bundles](/docs/operate/refreshing) for cleanup and repeat builds.

<NextSteps
  items={[
    {
      title: 'Install a bundle',
      href: '/docs/operate/installing',
      description: 'Review installation options and common errors.',
    },
    {
      title: 'Refresh a bundle',
      href: '/docs/operate/refreshing',
      description: 'Update an existing package request and clean up unused files.',
    },
  ]}
/>