Distrobox backups: images, package lists, and shared data

The command interfaces in this article were checked against the official Distrobox 1.8.2.5 scripts. Image tags and distribution package names are examples; before use, confirm that the image is still supported, the repositories are available, and the commands match your installed version. The examples have not been tested at runtime.

Package management inside a Distrobox guest is usually imperative, but image backups, package lists, and build declarations can complement each other. Save the container filesystem, runtime configuration, shared directories, data volumes, and application data separately so you can determine which assets a restore actually covers.

The following three approaches address image state, intended packages, and the creation process, respectively. None of them is a complete backup on its own.

1. Snapshot backup: podman commit#

podman commit captures a container's writable layer as an image and pauses the container during the commit by default. It is not a snapshot of memory or processes and cannot guarantee database consistency. Stop writes, stop services, or take an application-level dump first. Bind-mount and volume contents are not included by default.

Back up:

# 将当前容器状态固化为新镜像
podman commit arch my-custom-arch:latest
# 将镜像导出为压缩包存到宿主机
podman save my-custom-arch:latest | bzip2 > my-custom-arch.tar.bz

Restore:

# 从压缩包恢复镜像
bunzip2 -c my-custom-arch.tar.bz | podman load
# 用这个自定义镜像创建新的 distrobox
distrobox create --name arch-restored --image my-custom-arch:latest

If you use the Docker backend:

docker container commit -p distrobox_name image_name_you_choose
docker save image_name_you_choose:latest | gzip > image_name_you_choose.tar.gz

• Advantages: Preserves software and configuration in the guest's writable layer without reinstalling each item. The shared HOME, additional mounts, volumes, container runtime configuration, and in-process state must be restored separately.
• Disadvantages: Opaque state: you do not know exactly what is installed in the image, making this a less "elegant" approach. Image files can be large.

2. Export and replay a package list (lightweight)#

Instead of backing up the whole system, record which packages you installed and use the list to restore them after reinstalling.

Back up (inside the Arch container):

# 导出所有显式安装的包
pacman -Qqen > ~/arch-repo-pkglist.txt
# 外来包（包括 AUR），另存列表
pacman -Qqem > ~/arch-foreign-pkglist.txt

Because HOME is shared, this file is saved directly on the NixOS host.

Restore (inside a new Arch container):

sudo pacman -Syu
sudo pacman -S --needed - < ~/arch-repo-pkglist.txt

• Advantages: A tiny plain-text file that can be stored in Git.
• Disadvantages: AUR packages cannot be replayed directly through pacman. Check the sources of foreign packages and handle them separately with an AUR helper or a custom package build process. A list of names does not pin package versions, PKGBUILDs, or repository packages that have been removed.

3. Declarative builds (the recommended, NixOS-style approach)#

This approach truly fits the NixOS philosophy. Use distrobox.ini's additional_packages and hooks that run at the appropriate stage, or write a Dockerfile directly, to turn the packages inside your container into code as well.

3.1 Use distrobox.ini hooks (for a small number of packages)

Write the package list directly into the host's NixOS configuration:

xdg.configFile."distrobox/distrobox.ini".text = ''
  [arch]
  image=quay.io/toolbx/arch-toolbox:latest
  additional_packages=fish eza zoxide starship base-devel cmake
  additional_packages=rustup nodejs
'';

A manifest makes installation intent traceable; latest images and rolling repositories do not guarantee byte-for-byte identical results. An AUR helper is generally reviewed and built as a regular user after the guest's initial setup. Do not assume paru exists in a pre-init hook before the base packages have been configured.

3.2 A custom Dockerfile (for complex environments and traceable builds)

If your container environment is particularly complex, write a Dockerfile and manage it in Git:

FROM quay.io/toolbx/arch-toolbox:latest
RUN pacman -Syu --noconfirm && \
    pacman -S --noconfirm base-devel fish eza zoxide starship cmake rustup

Then build the image on the host:

podman build -t my-arch-dev:latest -f "$HOME/.config/distrobox/arch.dockerfile" .

Reference it in distrobox.ini:

[arch]
image=my-arch-dev:latest

• Advantages: Easier to rebuild and review. To pin results more closely, pin the base image digest, package repository snapshots, and download checksums. Track the Dockerfile and distrobox.ini in Git, in the same repository as configuration.nix.
• Disadvantages: Changes to the package list require another podman build.

Recommendations#

For most NixOS + Distrobox users, approach 2 (export a package list) combined with approach 3 A (distrobox.ini with additional_packages) offers the best balance of effort and benefit:

1. Put core system tools in distrobox.ini.
2. Export the development environment's package list as a txt file and keep it in a Git repository.
3. Manage configuration files, such as ~/.config/fish and paru.conf, in Git as well.

Then, even after reinstalling NixOS entirely, you can rebuild the container's package environment by pulling the Git repository → running distrobox-assemble create → replaying the package list. You will still need to restore data and exported entry points afterward.

4. Shared data and restore drills#

By default, HOME is a host directory and is not included in a commit/save image. A custom --home is also usually a host bind mount. Your backup should cover:

• The configuration, projects, and data in the shared or custom home that you actually need to restore. Avoid putting unprotected credentials in public Git repositories.
• Mounts, ports, devices, init/root modes, and manifests recorded with podman inspect; backing up only the image name is not enough.
• Data in named/anonymous volumes and additional bind mounts, plus consistent database dumps.
• distrobox.ini, build files, image digests, package lists, and any required upstream version/checksum records.

Rehearse restoration with a new container name and a new data directory first: load the image → create the container with the recorded parameters → enter it for initial setup → restore application data → check permissions, databases, and tool versions → export app/bin entry points again and verify that they launch. Replace the old environment only after these checks. Do not let the rehearsal container write directly to the only copy of production data.

distrobox rm deletes the guest filesystem; --rm-home may also delete a custom home. Cleanup and backup are different operations. Before deleting anything, verify the actual paths and the evidence that restoration works.