Installation

Installation

Choose between a native Linux installation and the prebuilt Docker image.

Method	What you install on the host
Native installation	Python 3.11+, the Python package and external system tools
Docker	Docker; the image already includes Python and the runtime tools

Docker

Download and check the prebuilt image from GitHub Container Registry:

docker pull ghcr.io/xitee1/bd-archiver:latest
docker run --rm ghcr.io/xitee1/bd-archiver:latest --version
docker run --rm ghcr.io/xitee1/bd-archiver:latest --help

Images are available for Linux AMD64 and ARM64. You do not need to install Python, DAR or PAR2 separately on the host to run them in the container. The image contains the latest published release, which can lag behind the source checkout.

Continue with the Docker guide for source/output volume mounts, example commands and building from source. Physical-drive access and ISO mounting need additional host/container setup; those requirements are explained there. The native installation steps below are an alternative to Docker.

Native installation

The native command targets Linux and requires Python 3.11 or newer. It uses Linux optical-drive discovery, mount tools and external archive utilities.

Install system tools

For all commands and ISO-based verification/restoration:

# Debian / Ubuntu
sudo apt install dar par2 growisofs dvd+rw-tools genisoimage libimage-exiftool-perl udisks2 build-essential linux-libc-dev

# Arch Linux
sudo pacman -Syu dar par2cmdline dvd+rw-tools cdrtools perl-image-exiftool udisks2 base-devel linux-api-headers

The executable names matter: filesystem sizing/creation calls mkisofs, capacity detection calls dvd+rw-mediainfo, and ISO mounting calls udisksctl. If your distribution packages these differently, install packages providing those commands. mount, umount and eject must also be available for physical-disc operations. lsof is optional and improves diagnostics for a busy drive. exiftool is required only for create --order-by content-date, where it reads content dates without changing media files or filesystem timestamps.

Minimal dependencies by operation

Operation	Required external commands
create / create -m raw	mkisofs; par2 unless -r 0; exiftool with --order-by content-date; dvd+rw-mediainfo unless -b is given
create -m dar	dar, mkisofs, dvd+rw-mediainfo; par2 unless -r 0
DAR creation with --pack-with	The above plus udisksctl only for ISO input; folders need no mounting tool
burn	growisofs, dvd+rw-mediainfo; mkisofs for folder input; post-burn verification also needs par2 if the disc has PAR2
verify directory	par2 only when PAR2 indices are present; SHA-512 verification runs in Python
verify ISO	The above plus udisksctl
extract	dar, par2; also udisksctl when -i includes ISO files

Two implementation details matter for minimal setups: DAR creation still checks for dvd+rw-mediainfo even with -b, and extract always checks for par2, even for an archive created with -r 0. dar is unnecessary for raw creation, burning and verification.

udisksctl needs a running udisks2 service, D-Bus and permission under the host's Polkit policy. Having the binary installed alone is not sufficient in a minimal container or some headless sessions. See Troubleshooting.

Native helper build requirements

Source and editable installations compile a small Linux C shared library for burn --write-timeout (default 180 seconds). Install a C compiler, libc development headers and Linux userspace headers; the package commands above include them. CC can select the compiler. Python development headers are not required.

The library is installed with the Python package, not in a global loader directory. The compiler is needed at build time only. Platform wheels contain the compiled helper and must match the machine architecture and C runtime; these are not universal Python wheels. The Docker image builds its own matching helper.

Burning requires a dynamically linked native ELF growisofs executable without setuid/setgid bits or file capabilities, and an accessible /proc/self/fd. Existing device access permissions are still required. Activation is checked before a burn; the program does not alter executable permissions automatically.

Install the Python command

With uv installed:

git clone https://github.com/Xitee1/bd-archiver.git
cd bd-archiver
uv tool install --editable .
bd-archive --help

This creates an isolated Python environment and exposes bd-archive on your user PATH. It does not install the external system tools. If the command is missing, run uv tool update-shell and restart your shell.

Keep the checkout in place: this is an editable installation, so source changes apply immediately for Python files. Changes to the native C helper or its build hook require rebuilding with uv tool install --force --editable .. After other checkout updates, refresh dependencies with uv tool upgrade bd-archive. If you move it, reinstall:

uv tool install --force --editable /new/path/to/bd-archiver

Uninstall the command with uv tool uninstall bd-archive. For a project-local virtual environment, see Development.

Shell completion

Add this to ~/.bashrc, or to ~/.zshrc after completion initialization:

eval "$("$(uv tool dir)/bd-archive/bin/register-python-argcomplete" bd-archive)"

For zsh, initialize completion first if your configuration does not already do so:

autoload -U compinit
compinit

For an activated project-local virtual environment, use:

eval "$(register-python-argcomplete bd-archive)"

Restart the shell. Completion covers commands, options and paths. The helper lives inside the tool environment; it need not be on your global PATH.

Drive selection

Without -D, the tool looks for /sys/block/sr* devices. It uses the only drive, asks you to choose if there are several, and fails if none are found. An explicit device must exist and be a block device.

Use -D /dev/sr0 with create, burn and extract. For verify, the device is positional: bd-archive verify /dev/sr0. For creation without a drive, pass the writable capacity in bytes with -b.

Next: Quick start.