butterknife

Archinstall-style TUI installer for Debian 13. An independent open-source project, part of the Butterbian family.

Terminal-based. No live desktop, no graphical installer. Boot the ISO, answer questions, pick a window manager, reboot into a configured system. BTRFS + Timeshift + grub-btrfs snapshot stack. Optional LUKS encryption. Optional SSHD.

Install

Download the ISO and read the install guide at butterbian.org. This repo is the source; most users don't need to build from it.

Snapshots

Subvolume layout: @ (root), @home, @var_log, @var_cache, @var_tmp. Logs, package caches, and temp files live in their own subvolumes so they don't bloat your rollbacks.

Timeshift writes snapshots to timeshift-btrfs/snapshots/ at the btrfs top level. There's no @snapshots subvolume. A snapshot is taken before every apt install, apt upgrade, and apt remove, and Timeshift keeps 8 weekly

• 12 monthly on its own schedule. Roll back from the GRUB menu via grub-btrfs.

Heads up if you've used Snapper on openSUSE or Arch: Timeshift manages its own snapshot location at the filesystem root, not a @snapshots subvolume mounted at /.snapshots.

Going further: full desktop environments

butterknife ships a minimal CLI base with a window-manager chooser on first login. If you'd rather run a full desktop (KDE Plasma, GNOME, Cinnamon, etc.), install the firmware and multimedia bits Debian's netinst pulls in before tasksel runs, then add the desktop meta-package:

# Firmware + video acceleration + codecs (what the Debian installer
# adds behind the scenes when you tick "Desktop" in tasksel)
sudo apt install \
    firmware-linux firmware-linux-nonfree firmware-intel-graphics \
    va-driver-all vdpau-driver-all \
    mesa-va-drivers mesa-vdpau-drivers libvdpau-va-gl1 \
    libavcodec-extra ffmpeg \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly gstreamer1.0-libav

# va-driver-all picks the right VA-API driver for your GPU automatically
# (older Intel, newer Intel, AMD). On newer Intel (Broadwell and up) you can
# optionally add intel-media-va-driver-non-free for extra codecs -- it needs
# the non-free component enabled and won't install on older Intel chips.

# Then pick a desktop:
sudo apt install task-kde-desktop
sudo apt install task-gnome-desktop
sudo apt install task-cinnamon-desktop
sudo apt install task-mate-desktop

Doing the codec/firmware step first means Timeshift's first apt-triggered snapshot captures a clean "minimal + multimedia" baseline before the desktop goes on top, so a broken DE install rolls back to a usable system instead of the bare CLI.

Build from source

Requires Debian (or a derivative) with debootstrap, xorriso, grub-efi-amd64-bin, grub-pc-bin, mtools, and squashfs-tools.

# Optional: build the offline rootfs tarball (bundles into the ISO,
# skips the need for internet during base install)
sudo bash build-rootfs.sh

# Build the bootable ISO
sudo bash build-iso.sh

Output: butterknife-<version>-trixie-<YYYYMMDD>.iso in the project root.

Architecture

Python + urwid TUI, no pip dependencies (urwid ships in Debian as python3-urwid). See HOWTO.md for a full walkthrough of the build pipeline and installer flow.

Part of the butter* Ecosystem

A JustAGuyLinux project, alongside Butterbian-XFCE, butterscripts, butterbash, butternotes, buttertodo, and butterrepo.

Support

Connect

• YouTube — tutorials and guides
• Butterforge — source code and projects
• The Butter Lab — Discourse forum
• The Churn — community chat (Fluxer)
• Wiki — documentation and guides
• Mastodon — @justaguylinux@fosstodon.org
• Butterbian — project home

License

GPL-2.0