Build 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:

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

You can also set backend in your 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, or build one as described in installation. Rename the extracted debark file to debark-linux-amd64 for this example, then supply it with --self-binary:

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.