English | 正體中文 | 简体中文 | 日本語 | 한국어

gentoo-install runs in a Linux live environment to install an amd64 Gentoo system. An interactive menu or a TOML configuration file specifies the installation. The interface is available in English, Traditional Chinese, Simplified Chinese, Japanese and Korean.

The paths below are implemented and have automated unit or plan coverage unless the verification status identifies a narrower boundary.

Storage. The device graph covers GPT and MBR; ext2, ext3, ext4, btrfs subvolumes, xfs, f2fs and vfat; swap; and LUKS2, LVM and mdraid. Existing partition tables can be retained, with a separate keep, format or delete decision for each partition.

The system configuration can configure zram independently of the device graph and swap partitions.

Boot and system. GRUB supports UEFI and BIOS, and systemd-boot supports UEFI. The installer configures systemd or OpenRC, dracut, locale, keyboard layout, timezone, hostname, DNS, static addresses and the selected network manager.

Desktop and language support. GNOME, KDE Plasma and Xfce are available with gdm, sddm or lightdm. Graphics settings cover AMD, Intel, NVIDIA and virtual machines. The package catalog includes fcitx5, Rime, Anthy, Mozc, Hangul and CJK fonts. The kernel choices include sys-kernel/gentoo-cjk-kernel-bin and sys-kernel/gentoo-cjk-kernel, both of which carry the cjktty patch.

Portage. The configuration covers the profile, MAKEOPTS, USE, ACCEPT_KEYWORDS, L10N, mirrors and repository synchronization. The gentoo-zh and gig overlays can be selected independently. Selecting zh-TW, zh-CN, ja or ko as the interface language also selects the gentoo-zh patched binary kernel and its overlay; selecting en does not. Official and gentoo-zh binary package sources have separate settings and keys.

Plan and records. A dry run prints an operation plan without probing storage hardware. A real installation uses the same planner after adding probed mdraid metadata for reused devices, so hardware-dependent validation can change the result. install.log records command output, and install.jsonl records operations, package sources and binary-package degradation reasons. Before uploading a configuration to paste.gentoozh.org, the menu replaces only password_hash and root_password_hash values with removed-before-publishing; the other configuration values remain in the upload. The menu displays the resulting page address as text and as a QR code.

Historical end-to-end records used the amd64 Gentoo minimal ISO at installer revisions a71f91b4735469bae8ec76af170201acb967a5fe and f7257793f95df4b21ebf2ac6a775a343f6205f1b. Those records covered selected UEFI and BIOS installations, systemd and OpenRC, ext4, btrfs, xfs, LUKS2, LVM, mdraid, Plasma and the official binhost, but later installation-path changes made them historical evidence only.

Revision-tagged end-to-end records dated 2026-08-11 cover one installation and boot from each of Arch Linux, openSUSE, Debian, Fedora and a self-built gentoo-cjk minimal ISO. The gentoo-cjk record uses ZFS and ZFSBootMenu; the other four use ext4. A run counts as current evidence only when its recorded revision matches the installer, its installation exit code is 0, the installed system boots and the post-boot configuration checks pass.

Other implemented combinations remain unverified end to end. Current evidence does not cover initramfs SSH unlock, greetd desktop sessions or ibus outside GNOME. It also does not cover the official Gentoo minimal ISO, Alpine or Gig-OS live media, or binary-host failure fallback.

CJK text-console rendering has no current verification evidence. ext2 and ext3 additionally have no focused automated configuration test. Files under tests/fixtures/ exercise the configuration model; their presence does not establish an end-to-end installation and boot result.

The IPv4-only, IPv6-only and dual-stack VM check stops before disk access. It checks address-family detection, bootstrap.sh --missing-commands and stage3 pointer retrieval; it does not verify stage3 download, repository synchronization, binhost access, package installation or a booted target system on those network modes.

A real installation requires root privileges, an amd64 target and Python 3.11 or newer. A configuration-file dry run does not require root privileges. The installer has no third-party Python runtime dependency.

The menu reads Gentoo main-tree package versions from packages.gentoo.org and gentoo-zh patched-kernel versions from api.github.com/repos/gentoo-zh/overlay/contents. It reads the maximum kernel version accepted by sys-fs/zfs from gitweb.gentoo.org. An installation from a configuration file requires the mirror that configuration names instead; --missing-commands and --config FILE --dry-run require none of these version endpoints.

The menu disables recorded IPv4-only Gentoo mirrors when the live environment has IPv6 but no IPv4.

bootstrap.sh reads /etc/os-release, reports missing commands and prints a candidate package-manager command. It recognizes these distribution families: Debian and Ubuntu; Arch; openSUSE; Fedora, RHEL and CentOS; Gentoo; and Alpine. The printed command must be reviewed before it is run.

A real run writes to the selected disks. A configuration-file run starts without a second erase confirmation; wipe = true, partition deletion and filesystem creation can destroy existing data.

Before a real run, the disk selectors and every destructive operation must be checked in the dry-run output. Stable /dev/disk/by-id/ selectors are preferable to names such as /dev/sda, and required data must have a separate backup.

The following commands download the current master archive and open the menu:

curl -fsSL https://github.com/Zakkaus/gentoo-install/archive/refs/heads/master.tar.gz | tar xz
cd gentoo-install-master
./bootstrap.sh

The menu requires an interactive terminal of at least 80x24 cells. It asks for the interface language once; --lang en selects English without that question.

The menu can save its answers as my-install.toml and exit. The configuration-file workflow below prints the complete plan before the real run:

./bootstrap.sh --config my-install.toml --dry-run
# Then one of the two below. Each writes the selected disks.
./bootstrap.sh --config my-install.toml
./bootstrap.sh --config my-install.toml --no-shell   # the same run, without the root-shell prompt

Before unmounting, an interactive run offers a root shell in the target after either success or failure. --no-shell suppresses that question.

--resume skips an operation recorded as complete only when its journal position and identity match the current plan and its effect is marked as surviving a reboot:

./bootstrap.sh --config my-install.toml --resume

Resume is limited to the same live session, the same installer revision and the same configuration file. The default journal is /run/gentoo-install/install.jsonl, so it does not survive a reboot. Each operation record contains an identity derived from that operation's class source and field values, so an operation whose identity changed is performed again rather than skipped. A change to a shared helper or constant is outside that identity, and the journal carries no digest of the configuration as a whole, so a different revision or configuration is outside the documented resume scope.

Configuration files use TOML. The top-level config_version field selects the schema version. Storage is a device graph: every device has an id, devices refer to other devices by id, and selectors are resolved only during a real run.

tests/fixtures/vm-binpkg.toml is a complete UEFI and ext4 schema reference. Other files under tests/fixtures/ cover BIOS, LUKS2, LVM, mdraid, ZFS, btrfs subvolumes and desktops. They contain virtual-machine disk selectors and test credentials, so they must not be installed unchanged on a real machine.

Parsing and planning do not probe storage hardware. A machine without the target disk can therefore check a configuration with --dry-run.

Binary packages are optional. Disabling them keeps source builds available. The official binhost and the gentoo-zh binhost are separate options with separate trust configuration. No current end-to-end evidence covers an unreachable binhost, a missing signature or an untrusted key; these degradation paths remain unverified.

For gentoo-install, 0 means successful completion and 1 means configuration error. 2 means an argparse usage error or preflight failure, and 3 means integrity failure. 4 means download, external-command, OS or uncategorized installer failure, and 5 means operator abort. bootstrap.sh can also exit 1 before the Python CLI starts when its Python, required-command or root checks fail.

CONTRIBUTING.md describes the development setup, architecture and required checks.