Skip to content

Distro Compatibility

Jump to bottom
Eugene Lazutkin edited this page Oct 11, 2026 · 3 revisions

Distro Compatibility

These dotfiles are regularly exercised on Debian/Ubuntu family, Red Hat family (Rocky, Alma, Oracle, Fedora, Amazon Linux), and tested on other distros to catch regressions. This page summarises support tiers, distro-specific notes, and what to do if the bootstrap install hangs or fails.

Support tiers

First-class

Full apt/dnf package install, tmux + plugins, /etc/sudoers.d/chezmoi, and Homebrew stack all work. Tested end-to-end through bootstrap-dotfiles.

Distro Notes
Debian 12 Bookworm ttyd not in stable repos (handled); libfuse2
Debian 13 Trixie ttyd still absent; libfuse2t64 native
Debian 14 Forky (Sid) ttyd now available; libfuse2t64
Ubuntu 22.04 LTS / 24.04 LTS LTS releases; libfuse2t64 on 24.04+, plain libfuse2 on 22.04 and earlier
Linux Mint 21.x Ubuntu 22.04 base; inherits its ecosystem
Pop!_OS Ubuntu-derived
Fedora (current release) Leading-edge dnf; bat native (no batcat alias needed)
Rocky Linux 9 EPEL + CRB auto-enabled
AlmaLinux 9 Rocky parity; interchangeable
CentOS Stream 9 Same codepath as Rocky/Alma
Oracle Linux 9 ID=ol, ID_LIKE=fedora — clone detection uses ID not ID_LIKE
Amazon Linux 2023 No EPEL-by-default; some EPEL-gated tools (bat, mc, tig) absent unless brew-installed
macOS (Intel + Apple Silicon) Homebrew in /opt/homebrew/ (Apple Silicon) or /usr/local/ (Intel)

Best-effort (generic branch)

Bootstrap falls through to the unsupported-distro branch. Homebrew + chezmoi-managed configs install and work, but distro-specific pieces are skipped:

  • No system-package install (the apt/dnf pre-install list is gated on pkgManager, so tmux, bat, ripgrep, httpie, etc. won't arrive unless you install them via your distro's package manager or via brew).
  • No /etc/sudoers.d/chezmoi rules (the script guards on a known sudo group name).
  • No tmux plugins (tmux itself wasn't installed).
Distro Notes
Arch Linux pacman; pre-install base-devel git curl tar file ca-certificates
openSUSE Tumbleweed / Leap zypper; openssh (not openssh-server); per-package install works better than devel_basis pattern
Gentoo, Void, Slackware, Devuan Untested but expected to follow the same generic-branch pattern

To promote any of these to first-class would require adding a pacman/zypper/etc. branch to .chezmoi.toml.tmpl, run_onchange_before_install-packages.sh.tmpl, and run_onchange_after_install-sudoers.sh.tmpl. Not currently planned — contributions welcome.

Unsupported

Distro Why
Alpine Linux Uses musl libc. Homebrew explicitly requires glibc ≥ 2.13; its installer aborts on musl. The bootstrap script fails cleanly at the "Homebrew not found" check — no partial state written.
WSL (Windows Subsystem for Linux) Should work as the underlying Ubuntu/Debian, but GUI-gated packages such as meld are skipped with hasGui=false.
BSD family (FreeBSD, OpenBSD, NetBSD) Different kernel and userland; GNU/systemd/bash-4+ assumptions throughout. Out of scope.

Distro-specific quirks worth knowing

  • Pre-installed tmux breaks tpm: on distro images that ship tmux (Ubuntu 24.04 LXC), if you attach via ssht before chezmoi clones tpm, the tmux server starts without TMUX_PLUGIN_MANAGER_PATH set. The bootstrap fix seeds that variable before install_plugins runs; no action needed from users.
  • curl vs curl-minimal: Amazon Linux 2023 ships curl-minimal which conflicts with the full curl package. The RHEL branch of the installer deliberately omits curl from its dnf list — curl-minimal provides the binary.
  • EPEL availability: Rocky/Alma/Oracle install cleanly; Amazon Linux 2023 has no epel-release in its default repos so EPEL-gated tools are silently dropped. Install them via brew if needed.
  • Oracle Linux's ID_LIKE=fedora: unlike Rocky/Alma/CentOS which declare "rhel centos fedora", Oracle declares only "fedora". Clone detection uses ID (not ID_LIKE) to avoid matching Oracle as real Fedora.
  • Mint's ID_LIKE="ubuntu debian": first-word-of-ID_LIKE would be ubuntu, not debian. Package-manager detection scans the whole ID+ID_LIKE string for known keywords.
  • Debian lacks ID_LIKE: ID=debian alone — direct ID match handles this.
  • SELinux is Enforcing on bare-metal Fedora/RHEL: the LXC test images disable it. If you hit file-context issues with /etc/sudoers.d/chezmoi or systemd user units, run sudo restorecon -Rv /etc/sudoers.d/ after chezmoi apply.

If the install hangs or fails

The bootstrap flow is idempotent: install.sh (curl-pipe) and chezmoi apply can both be re-run safely. If something breaks mid-way, you can usually just re-run the script.

Symptom: install hangs silently on brew update or git clone

Likely IPv6 routing issue. Containers, some VPS providers, and occasional corporate networks hand out ULA or unreachable IPv6 addresses. When DNS returns both A and AAAA records, curl / git pick IPv6 first and stall indefinitely.

Quick fix:

sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1

Then re-run curl -fsSL https://raw.githubusercontent.com/uhop/dotfiles/main/install.sh | sh. To make the change persistent, add the two sysctl lines to /etc/sysctl.d/99-disable-ipv6.conf.

Alternatively, configure glibc to prefer IPv4 via /etc/gai.conf:

precedence ::ffff:0:0/96  100

Symptom: Homebrew's installer asks for a password even though you have passwordless sudo

Happens when the user is in the sudo/wheel group AND also has a separate /etc/sudoers.d/<user> entry with NOPASSWD. The group rule requires a password, and sudo -v (called by Homebrew's installer) prompts if any matching rule needs one — even when a later NOPASSWD rule exists.

Simplest fix for an interactive install: just type your password once. Homebrew caches sudo for 5 minutes; the rest of the install rides that cache.

Symptom: "Homebrew not found" after you just installed it

The installer adds Homebrew to /home/linuxbrew/.linuxbrew/ (Linux) or /opt/homebrew/ (macOS Apple Silicon) but doesn't modify the current shell's $PATH. Either source shellenv manually and re-run:

eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"   # Linux
# or
eval "$(/opt/homebrew/bin/brew shellenv)"                # macOS AS
curl -fsSL https://raw.githubusercontent.com/uhop/dotfiles/main/install.sh | sh

Or start a fresh shell (log out and back in, or exec bash -l) — chezmoi's .bashrc sources Homebrew automatically once deployed.

Symptom: install.sh aborts with a package-install error

Take note of the failed package name, install it manually with your distro's package manager (or skip if you don't need it), and re-run the script. Chezmoi's run-once and run-onchange scripts are designed to resume cleanly.

Symptom: chezmoi prompts asking name, email, GitHub username again on re-run

The prompts use promptStringOnce which stores answers in ~/.config/chezmoi/chezmoi.toml. If that file got removed or corrupted, chezmoi re-prompts. Accept defaults or re-enter — the rest of the apply uses the stored values.

Related pages

🔍 Search the wiki

dotfiles

Initial setup

General information

Day-to-day operations

Clone this wiki locally