🔪 Archinstall-style TUI installer for Debian 13 — BTRFS + Timeshift + grub-btrfs, configured from day one. https://butterbian.org
  • Shell 54.9%
  • Python 43.6%
  • CSS 1.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-06 12:58:33 -05:00
assets - upscale lightdm greeter wallpaper to 3344x1882 (real-esrgan via upscayl) — sub-fhd source was soft on modern monitors 2026-05-01 00:51:20 -04:00
lib 700-permission mk-temp directory issue 2026-09-17 13:06:12 -04:00
overlay Overlay copy no longer leaves system directories group-writable (issue 17) 2026-09-15 12:01:03 -04:00
.gitignore gitignore: stop tracking CLAUDE.md and ignore .claude/ 2026-05-24 19:33:24 -04:00
build-iso.sh Locale: validate typed locales against SUPPORTED; ship locales in the live ISO 2026-09-10 15:10:01 -04:00
build-rootfs.sh 700-permission mk-temp directory issue 2026-09-17 13:06:12 -04:00
build.log updated mbr structure 2026-08-13 12:43:06 -04:00
butterknife update 2026-04-16 21:58:17 -04:00
butterknife-bash Disk picker filters out floppy devices 2026-08-16 17:44:33 -04:00
CONTRIBUTING.md Add contributing stub 2026-09-15 10:14:32 -04:00
HOWTO.md 700-permission mk-temp directory issue 2026-09-17 13:06:12 -04:00
push-dev.sh - add push-dev.sh: push dev, fast-forward main from it, push main (refuses if main isn't a ff target) 2026-04-30 21:00:15 -04:00
README.md consistent readme footer 2026-11-06 12:58:33 -05:00
RELEASE.md 700-permission mk-temp directory issue 2026-09-17 13:06:12 -04:00
tag-release.sh - add tag-release.sh: create + push annotated tag matching VERSION, with safety checks (existing tag, dirty tree, unpushed HEAD) 2026-04-30 20:57:51 -04:00
VERSION 700-permission mk-temp directory issue 2026-09-17 13:06:12 -04:00

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.

Window managers

At the end of the install a chooser offers these, each installed and configured from its Butterforge setup repo:

X11

  • awesome - highly configurable tiling WM (Lua)
  • bspwm - binary space partitioning WM
  • dwm - dynamic window manager (suckless)
  • i3 - tiling WM with great documentation
  • openbox - configured stacking WM (Butterbian)
  • oxwm - dwm-like WM in Zig, Lua config with hot-reload
  • qtile - tiling WM written in Python

Wayland

  • sway - i3-compatible Wayland compositor
  • mangowc - dwl-based compositor with animations, blur, and rounded corners (scenefx). Pinned to 0.14.4, the last release that builds on trixie; mangowc-setup explains why.

You can pick more than one and switch between them at the login prompt. The chooser can also install full desktop environments (KDE, GNOME, COSMIC, and more) or optional tools (printing, bluetooth), or be skipped entirely for a console-only system. Rerun it any time with /usr/lib/jagl/wm-chooser.

Going further: full desktop environments

If you'd rather run a full desktop than a window manager, pick the desktop option in the end-of-install chooser (or rerun /usr/lib/jagl/wm-chooser later). It installs the firmware, VA-API/VDPAU drivers, and codecs that Debian's netinst normally adds behind the scenes, then your chosen desktop (KDE Plasma, GNOME, Cinnamon, XFCE, MATE, LXQt, or COSMIC) with its display manager. Everything runs through apt, so the pre-invoke hook snapshots the system first and a broken desktop install rolls back to the working CLI base.

Prefer to do it by hand? Install the firmware/codec packages first, then a task-*-desktop meta-package. The package list lives in butterscripts/setup/optional_tools.sh.

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

Buy me a coffee

Connect

License

GPL-2.0


Made with 🧈 by JustAGuyLinux