- Shell 54.9%
- Python 43.6%
- CSS 1.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| assets | ||
| lib | ||
| overlay | ||
| .gitignore | ||
| build-iso.sh | ||
| build-rootfs.sh | ||
| build.log | ||
| butterknife | ||
| butterknife-bash | ||
| CONTRIBUTING.md | ||
| HOWTO.md | ||
| push-dev.sh | ||
| README.md | ||
| RELEASE.md | ||
| tag-release.sh | ||
| VERSION | ||
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
@snapshotssubvolume 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
Connect
- YouTube — tutorials and guides
- Butterforge — source code and projects
- Butter desktops — ready-to-use window manager desktops for Debian
- The Butter Lab — Discourse forum
- The Churn — community chat (Fluxer)
- Wiki — documentation and guides
- Mastodon — @justaguylinux@fosstodon.org
- Butterbian — a maintained Debian derivative built on Debian stable
License
GPL-2.0
Made with 🧈 by JustAGuyLinux
