# Build backends

Choose native apt or a container to download packages for your target release.

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

---
A **backend** is where Debark runs apt to work out which packages to download. You usually
don’t need to choose one: the default, `auto`, selects it for you.

## Choose a backend

| Setting     | When to use it                                              | Requirements                                              |
| ----------- | ----------------------------------------------------------- | --------------------------------------------------------- |
| `auto`      | The default for most builds                                 | Compatible local apt, or Docker / Podman                  |
| `local`     | Build on a compatible Debian or Ubuntu computer             | apt compatible with the target release                    |
| `container` | Build for another release, or from another operating system | Docker or Podman and a Linux CLI binary for the container |

To select one for a build:

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

You can also set `backend` in your [configuration](/docs/reference/configuration), or use
`DEBARK_BACKEND`.

## How automatic selection works

Debark checks whether the online computer’s apt can reproduce the target’s dependency decisions.
It considers the release and apt’s dependency solver, the part of apt that selects packages.
Matching apt version numbers alone aren’t enough.

If compatibility is confirmed, `auto` uses local apt. Otherwise, it uses a container.
Forcing `local` when the systems don’t match ends the build with exit 2.

Both backends use the snapshot’s package state and settings in a temporary apt directory.
They don’t change your online computer’s system apt configuration.

## Set up containers

Install Docker or Podman and make sure your user can run it. Debark normally checks for Docker
first, then Podman. To choose explicitly, set `container_runtime: podman` in the
configuration or set `DEBARK_CONTAINER_RUNTIME=podman` in your environment.

The container uses a distribution image for the target release. Common defaults include:

| Target       | Image                  |
| ------------ | ---------------------- |
| Debian 12    | `debian:bookworm-slim` |
| Debian 13    | `debian:trixie-slim`   |
| Ubuntu 22.04 | `ubuntu:22.04`         |
| Ubuntu 24.04 | `ubuntu:24.04`         |
| Ubuntu 26.04 | `ubuntu:26.04`         |

The first build may take longer while the image downloads. If you use `--image` to override
it, choose an image compatible with the target.

## Building on Windows or macOS

The container needs a static Linux build of the CLI. Your Windows or macOS executable cannot
run inside it.

Download and verify the matching [Linux CLI archive](/download#cli), or build one as described
in [installation](/docs/get-started/installation#copy-to-the-offline-machine).
Rename the extracted `debark` file to `debark-linux-amd64` for this example, then supply it
with `--self-binary`:

```bash
debark build --snapshot target.tar.zst --out ./bundle \
  --backend container --self-binary ./debark-linux-amd64 \
  --sign operator.key jq
```

Match the binary to the architecture used by the container. You can save its path in
`self_binary` or `DEBARK_SELF_BINARY`. Windows has limited recorded container validation;
macOS has no CI or recorded container run. A WSL installation alone is not a backend for
the native Windows CLI: either run the Linux CLI inside WSL, or use the native Windows
CLI with Linux containers and the helper above.

## If the backend fails

Exit 2 usually means a required tool is missing, the container runtime cannot start, or local
apt is incompatible. Check the error message, confirm the runtime works for your user, and
try `auto` or `container` if you previously forced `local`.

Verification and inspection don’t need a container. Installation runs on the Debian or Ubuntu
target with its own apt and dpkg.

<NextSteps
  items={[
    {
      title: 'Installation',
      href: '/docs/get-started/installation',
      description: 'Build the CLI for your online and offline computers.',
    },
    {
      title: 'Troubleshooting',
      href: '/docs/operate/troubleshooting',
      description: 'Find help with container and apt errors.',
    },
  ]}
/>