Stage file

This page contains changes which are not marked for translation.

Other languages:

A stage file (also known as a stage tarball) is an archive that contains all the files to run a minimal Gentoo environment, typically to serve as a seed for a Gentoo installation.

Gentoo provides a selection of stage 3 files for download, to cater to different installation configurations, on supported architectures.

Other stage files are used for internal Gentoo Linux development purposes. Customized stage files can also be created for specific requirements, if needed.

Note
Only stage 3 files are used for installation, stages 1 and 2 are for development purposes only.

Official Gentoo stage files

This section is a work in progress; treat its contents with caution - ris (talk | contribs).

Gentoo's Release Engineering team offers stage 3 files for download for installing Gentoo Linux. They are distributed via the mirror system.

The Gentoo stage files are built for a given architecture for selected profiles.

The internal system uses Catalyst to create the stage files according to a set of spec files.

Choosing a stage file for installation

First think about what a system will be used for, the two main consideration are:

If the installation is to be a desktop system to be used with a graphical interface, or system purely used form the Command Line Interface, such as a server system
Whether the system will use the OpenRC or systemd init system

The choice of stage 3 to use for installation is tightly coupled with what profile will be selected later on in the installation. While it's possible to easily switch between certain profiles after installation, other switches can be more involved (e.g. switching init systems), with some requiring substantial effort and consideration, or even be impossible without complete re-installation. Thus it is important to choose wisely, and conservative choices are recommend for anyone who doesn't have specifc needs that require other stage 3/profile choices.

Important
Switching between some profiles can require substantial effort and consideration, for example switching init systems is difficult, and switching from no-multilib to multilib requires extensive Gentoo and low-level toolchain knowledge. It is not possible to change to profiles with different ABIs (e.g. pure LLVM or musl profiles), and reinstallation would be the only way to move between such profiles.

Note
The stage files described below will often be available only for certain architectures.

The most basic stages will only have the name of the init system in their name (OpenRC or systemd), stage3-<architecture>-openrc or stage3-<architecture>-systemd. These stages are for Command Line Interface only systems, such as for servers, for use in containers, etc.

Desktop stages

Desktop stages target a desktop environments (graphical/GUI). The USE flags on desktop stage file are fine tuned to enable all the basic requirements a desktop system will need such as video and audio playback plus sound support.

These stages include packages such as llvm-core/llvm and dev-lang/rust-bin and can save many hours off the install, over trying to convert one of the other stages to a desktop system.

These stage 3 files have the word "desktop" in their name.

Experimental stages

These are often used by testers. They should only be used when specifically required, for general-use pick a stable stage file.

LLVM and/or Musl stages are for advanced and specific installs types. As a general rule thumb the user will know when there is a need for them, rather then looking for a need to use one.

Note that musl users will find many common programs no longer being able to work without the use of workarounds. Steam is one of the common issues user have with not working under musl.

LLVM users will find many programs are no longer able to compile for various reasons. For that reason alone it is expected for users to be able to report issues, look for patches or write their own and report this back to Gentoo and upstream project where possible.

It is not possible to switch back to glibc or GCC system without reinstalling Gentoo.

No-multilib stages

Warning
Switching from no-multilib to multilib is difficult to the point that it is usually preferred to reinstall rather than to switch between these profiles.

Tip
Using multilib targets makes it easier to switch profiles later, compared to no-multilib

The multilib profile uses 64-bit libraries when possible, and falls back to the 32-bit versions when necessary. This is an excellent option for the majority of installations because it provides a great amount of flexibility for customization in the future.

Selecting a no-multilib tarball to be the base of the system excludes 32-bit system libraries. This will stop some apps from working, such as most games on Steam. There are workarounds for this, however they can be very involved, so if any use of 32 bit software might be required in the future, no-multilib stage file should not be used.

It should be noted that if a user wishs to switch back to multilib at a later time, then reinstalling is often the only practical way to do so.

Stages by number

Stage 3

Stage 3 files are available on main website's downloads page and are hosted on distfiles.gentoo.org (navigate to the <arch>/autobuilds/ directory).

Downloading and decompressing a stage 3 file, as described in the handbook's stage file section, will install an almost-complete and mostly-functional system (the most important parts still missing are a kernel and a bootloader).

Tip
The desktop stage files provide extra packages to help setup desktop systems more easily. If planning on installing a desktop system, using a desktop profile, choose the corresponding archive.

See also
See the handbook sections entitled what are stage files? and choosing a stage file for more information about stage 3 files.

Stage 3 files are compiled from stage 2 files, but contain a @system set of packages.

Not including sub-profiles, the base file used for the system set of all profiles can be found at: /var/db/repos/gentoo/profiles/base/packages.

Stage 4

Important
A "stage 4" file is a loosely defined term that generally just means a stage 3 with 'extra bits'.

Official "stage 4" files were previously available in January 2016 for the amd64 architecture.

A cloud "stage 4" has been created to aid in the process of virtual machine provisioning. These stage 4 files can be used with diskimage-builder (available via app-emulation/diskimage-builder). See the Gentoo README upstream and official diskimage-builder documentation for more information.

Catalyst is a tool for power users to create a stage4 with all the packages they require by default.

Internal development stages

Note
These stages are used by Gentoo developers to bootstrap the system for release, and are generally not intended for other uses.

Being mostly for development purposes, stage 1 or stage 2 files are unavailable for download.

Stage 1

Stage 1 files are generated from a packages.build file. Each system profile may have a slightly different packages.build file:

var/db/repos/gentoo/profiles/arch/riscv/packages.build
var/db/repos/gentoo/profiles/default/linux/musl/packages.build
var/db/repos/gentoo/profiles/default/linux/packages.build
var/db/repos/gentoo/profiles/default/linux/uclibc/packages.build
var/db/repos/gentoo/profiles/features/musl/packages.build
var/db/repos/gentoo/profiles/features/uclibc/packages.build
var/db/repos/gentoo/profiles/targets/systemd/packages.build

Stage 2

Stage 2 files contain the same packages as a stage 1 file with one caveat: stage 2 files are compiled from a stage 1 file. This is to ensure the stage 1 file contains the tool chain necessary to reproduce itself.

Creating stage files

Stage files are generated with catalyst using appropriate specs files.

External resources

https://www.gentoo.org/downloads/ - Gentoo download page with links to official stage files.