Butterbian

Debian 13 with BTRFS, Timeshift, and grub-btrfs preconfigured. Two editions — XFCE for "I want a desktop" and butterknife for "I want to build my own."

Project site: butterbian.org · Source: Butterbian-XFCE · butterknife

---

The story

Butterbian has been a couple of years in the making. The throughline is one idea: your system should be snapshotted before anything breaks it. Most distros leave BTRFS and Timeshift as exercises for the user — partition layouts, subvolume names, grub-btrfs hookups, Timeshift rules. Butterbian does that wiring for you so you can roll back from the GRUB menu when something goes sideways.

That single goal grew sideways into a small ecosystem. Each piece exists because the bigger project needed it:

• butterknife — an archinstall-style TUI installer for Debian 13. Built because there wasn't a clean "install Debian and pick a window manager" path that respected the snapshot setup.
• WM-setups — preconfigured DWM, Sway, BSPWM, Awesome, i3, Openbox, Qtile. butterknife's WM picker installs whichever you choose, fully configured.
• butterrepo — a community APT repository for software Debian doesn't ship (or doesn't ship recent enough): Ghostty, Neovim built from source, rofi 2.0, Zen Browser, Helium, ly, picom.
• butterbash — sane bash config for people who don't want to write their own.
• butterscripts, butternotes, buttertodo — small tools that solved specific itches along the way.

None of these were planned upfront. Butterbian needed an installer → butterknife. Butterknife needed working WM configs → wm-setups. Some apps weren't packaged the way I wanted → butterrepo. The ecosystem grew sideways from the central project.

Background reading on BTRFS: several of my YouTube videos cover BTRFS, snapshots, and Timeshift in depth — they're some of my most-watched content. See the JustAGuyLinux YouTube channel for the long version of why this stack exists and how it works.

---

Editions

Same snapshot stack underneath. Pick the one that matches how you want to spend your evening.

	XFCE	butterknife
For	"I want a desktop"	"I want to build my own"
Installer	Calamares (graphical)	TUI (Python + urwid)
Live env	Full XFCE desktop	Bare terminal
First boot	Themed XFCE desktop	Your chosen WM, configured
Filesystem	BTRFS only	BTRFS, ext4, or XFS
Firmware	UEFI only	UEFI or legacy BIOS
Encryption	—	LUKS on BTRFS, ext4, or XFS
ISO size	~2.5 GB	~1 GB

XFCE — the full spread

Boot the ISO, click through Calamares, reboot into a themed XFCE desktop. Everything's already configured — theme, icons, cursors, panel, terminal. Build/contributor reference: Butterbian-XFCE.

• MacTahoe GTK theme, icons, cursors — polished macOS-inspired look
• Customized xfce4-terminal and xfce4-panel
• Calamares graphical installer
• butterbash shell config

butterknife — choose your spread

An independent, archinstall-style TUI installer for Debian 13. Boot the ISO, answer questions in a terminal installer, pick a window manager from the menu, reboot into your configured system. WM configs come from the JustAGuyLinux setup repos. Build/contributor reference: Butterknife.

• Python + urwid TUI
• BTRFS, ext4, or XFS · UEFI or legacy BIOS
• Optional LUKS (BTRFS, ext4, XFS) · optional SSHD
• Chroot recovery built into the live env
• WM picker — 7 preconfigured setups (dwm, awesome, bspwm, i3, openbox, qtile, sway)

---

The snapshot stack

What both editions get when you choose BTRFS:

• BTRFS filesystem with preconfigured subvolumes (see below)
• Timeshift configured and ready on first boot
• grub-btrfs — roll back from the GRUB menu, no live USB needed
• Automatic snapshot before every apt/dpkg operation
• Apt snapshots pruned automatically after 30 days
• zram swap — no swap partition needed
• Offline installation — no internet required during install

butterknife also installs on ext4 or XFS. You keep zram and offline install, but snapshot features are BTRFS-only — that's how Timeshift and grub-btrfs work.

---

Subvolume layout

Subvolume	Mountpoint
@	/
@home	/home
@snapshots	/.snapshots
@var_log	/var/log
@var_cache	/var/cache
@var_tmp	/var/tmp

@var_log, @var_cache, and @var_tmp are separate so they're excluded from Timeshift snapshots automatically. No cruft in your rollbacks.

Note: LUKS on BTRFS uses an unencrypted 1 GB /boot partition — required so GRUB can load the kernel. Snapshots and grub-btrfs rollback work as normal on encrypted BTRFS installs. Home-directory encryption on BTRFS without full-disk LUKS is planned for a future release.

---

Theming

XFCE edition:

• MacTahoe GTK theme — polished macOS-inspired look
• MacTahoe icon theme — matching icon set
• MacTahoe cursors — consistent cursor theme
• Customized xfce4-terminal — colors and font tuned out of the box
• Customized xfce4-panel — with buttery customization

butterknife:

• Optional Butterbian-themed lightdm-gtk-greeter (line-art wallpaper, "b" avatar) — opt-in during install
• No desktop theming — each WM config brings its own look
• Theming lives with the WM setup repo you pick at first login

---

Requirements

	XFCE	butterknife
Firmware	UEFI only	UEFI or legacy BIOS
CPU	64-bit (amd64)	64-bit (amd64)
RAM	4 GB minimum	2 GB minimum
Disk	20 GB	10 GB (more for heavy WM stacks)

---

butterrepo

butterrepo is a community APT repository providing fresh, GPG-signed packages for Debian users — no tracking, no analytics. It's preconfigured on both Butterbian editions, so packages are available immediately after install.

Available packages:

• fzf
• Geany + plugins
• Ghostty
• Helium Browser
• ly (display manager)
• Neovim (built from source)
• picom
• rofi 2.0
• Zen Browser

Also works standalone on Debian 12+, Ubuntu 22.04 LTS+, and other Debian-based distros.

---

Download

get.butterbian.org — both XFCE and butterknife ISOs.

---

Issues & feedback

• XFCE: Butterbian-XFCE/issues
• butterknife: butterknife/issues

---

Related

• DWM Setup wiki — the suckless dwm wm-setup that ships as a butterknife option
• My Setup — the production machine that runs Butterbian
• Codeberg — why I left GitHub