Handbook Talk:AMD64/Installation/Base

True multilib needs modification in make.conf
When installing selecting the multilib profile itself wasn't sufficient. I only got true multilib support after adding the follwing in make.conf. I think it's worth mentioning it upfront so that people wouldn't have to recompile @world ABI_X86="64 32"


 * No, this is not a good suggestion to make for all Gentoo users to read the Handbook. We recommend only setting enable  as-needed on a per-package basis, not globally. As explained by, "if you enable ABI_X86="32" globally up front, you save a little bit of user configuration time up front but you waste a lot of compile time on every upgrade forever". Also, if this was set globally as you suggest, revising those packages later can cause headaches. Kind regards, --Maffblaster (talk) 19:30, 3 October 2016 (UTC)

Chroot on one line
It would be imo convenient to have one-liner for the mounts before the chrooting, instead of five separate commands, so that one could easily copy-paste the one command to terminal and execute it in one take

I.e., instead of (or, placed after)

root #mount -t proc proc /mnt/gentoo/proc root #mount --rbind /sys /mnt/gentoo/sys root #mount --make-rslave /mnt/gentoo/sys root #mount --rbind /dev /mnt/gentoo/dev root #mount --make-rslave /mnt/gentoo/dev

there ought to be also

mount -t proc proc /mnt/gentoo/proc && mount --rbind /sys /mnt/gentoo/sys && mount --make-rslave /mnt/gentoo/sys && mount --rbind /dev /mnt/gentoo/dev && mount --make-rslave /mnt/gentoo/dev

--Renergy (talk) 19:39, 6 June 2015 (UTC)


 * Renergy, I can see that may be easier to copy and paste a one line command such as you posted above. Part of the purpose of the Handbook is to teach people how to install Gentoo Linux, not to make the install as fast as possible, which is why we have each command on a separate line. I will think about putting a one-liner like you suggest as a secondary option for people who are in a hurry. Sincerely, --Maffblaster (talk) 22:14, 21 December 2015 (UTC)

Potential security problem
Going though the handbook normally leads you through getting the minimal .iso and stage 3 tarball over https, checking hashes and verifying with gpg. All good so far. Here, it tells users to run emerge-webrsync, without any warning that it defaults to using http - enabling a MITM attack. If I understand correctly, this is for downloading and setting up portage, while running as root. By default, emerge-webrsync does not verify gpg signatures, so at this point the system must be considered fundamentally insecure.

The user stanley on irc suggested using this procedure: Handbook:AMD64/Working/Features - it should definitely be mentioned as an option at this stage, since doing it with an already insecure system at the later stage will make little difference.

Also, emerge-webrsync should default to using HTTPS.

--OliverUv (talk) 12:26, 28 June 2015 (UTC)


 * But this affects all arches, right? See Handbook_Talk:Parts/Installation/Base --Charles17 (talk) 17:43, 20 January 2016 (UTC)


 * Hm...I'll see what we can do about this upstream. It would be nice if the mirrors used HTTPS, but I'm not sure we have a good way of enforcing it. --Maffblaster (talk) 18:21, 18 November 2016 (UTC)


 * So, the good news is that current Gentoo minimal install images ship with a sufficiently modern Portage (>=2.3.42, with the  USE flag set) such that for a vanilla -based  (under the recommended  settings from the guide:   etc.), signature verification with failure quarantine will be carried out.


 * The not so good news is that in this section of the handbook, it is still recommended first to carry out a vanilla, which for some mirrors anyway will use unauthenticated HTTP (e.g. http://trumpetti.atm.tut.fi/gentoo), and which does not (by default) signature verify the downloaded tree.


 * This is easy enough to work around though - just set  in the  section of, temporarily set   in that file also (rather than  ) and then issue  . This will do all the necessary signature updating etc and then download and verify the daily snapshot (NB -  will complain if you try to directly invoke it with   set; you need to use  or ). Then, once done, just flip back to using  . This ensures all updates are validated, and doesn't mess the flow of the guide up too much. (I'm just in the process of switching over to recommending this workflow for my own EFI install guide, incidentally.) --Sakaki (talk) 13:33, 11 October 2018 (UTC)

Choosing profiles
I believe profiles should be chosen after the initial reboot at least for and. Choosing a desktop profile, in particular, too early causes increased and unnecessary install time added to a user's experience.

I think it should be saved until the first reboot.

--Grknight (talk) 01:46, 22 October 2015 (UTC)


 * I will experiment on a virtual machine with this. My initial thoughts are that you're right. Rebuilding world after the profile selection is probably not a necessary part of the process. --Maffblaster (talk) 23:28, 1 February 2016 (UTC)


 * Also, the profile selection should be updated to 17.0, maybe with a little warning regarding 17.1 which got stabilized recently.--Charles17 (talk) 10:28, 27 December 2017 (UTC)

Update in progress... --Maffblaster (talk) 02:44, 28 April 2018 (UTC)

Add -qt5 USE flag
Let me quote: "gnome gtk -kde -qt4 will compile programs with GNOME (and GTK) support, and not with KDE (and Qt) support, making the system fully tweaked for GNOME (if the architecture supports it)."

Please add -qt5 to the previous sentence as well.

Fturco (talk) 15:25, 16 April 2017 (UTC)


 * Good suggestion. Consider it done. --Maffblaster (talk) 06:35, 14 May 2017 (UTC)

Will we need Section of "Mounting the boot partition"?
Hello, Operation of this section is already executed in section of "Preparing the disks".

Haven't we mounting /dev/sda2 on /boot already?

Kind regards, --Komainu8 (talk) 11:04, 13 May 2017 (UTC)


 * It depends on what install path you take. With this being said, the entire disk section(s) of the Handbook need a major reworking, so I would not be surprised if mounting is inconsistently noted here. I'll leave this open for now since no one is ready to work on fixing the disk section yet... --Maffblaster (talk) 06:39, 14 May 2017 (UTC)


 * It would be great to have such thing mentioned. --Wowpetr (talk) 09:25, 12 July 2017 (UTC)


 * In this discussion, undoing the creation of the /boot directory was accepted, but mounting is still required depending "on what install path you take". If so, wouldn't be informative to display this in the instructions? I know that if you try to re-mount a partition to the same directory is harmless (no messages are displayed on the shell after execution) but it would be even more educational to the new user to know if this is expected. If not, maybe consider delete this subsection?--Neyuru (talk) 20:03, 5 April 2020 (UTC)

Mounting the necessary filesystems
It is good to mention that if you interrupt the installation process at any stage later (e.g. by rebooting), you may need to mount these partitions again. --Wowpetr (talk) 09:25, 12 July 2017 (UTC)


 * Thanks for the tip. Your suggestion has been implemented! --Maffblaster (talk) 23:34, 25 July 2017 (UTC)

Entering the new environment
It is good to mention that if you interrupt the installation process at any stage inside chroot environment (e.g. by rebooting), you need to chroot again. --Wowpetr (talk) 09:39, 12 July 2017 (UTC)


 * Thanks for the tip. Your suggestion has been implemented! --Maffblaster (talk) 23:34, 25 July 2017 (UTC)

Warning about 17.x profiles
Please add a big warning before the profile selection instructions, to tell users not to use 17.0 or 17.1 profiles until they have read the corresponding news items and are prepared to follow the migration instructions.

Iamben (talk) 15:34, 29 December 2017 (UTC)


 * Done. --Maffblaster (talk) 02:39, 28 April 2018 (UTC)

Typo correction
Right at the bottom of the page, the line

root #env-update && source /etc/profile && export PS1="(chroot) $PS1"

should read

root #env-update && source /etc/profile && export PS1="(chroot) ${PS1}"

to properly maintain consistency with the previous command under Entering the New Environment

Redchillipadi (talk) 02:54, 27 April 2018 (UTC)


 * It looks that way to me, . What's the exact link that you're seeing just ? --Maffblaster (talk) 02:38, 28 April 2018 (UTC)

My browser says PS1 is mentioned under Entering the new environment as  and at the bottom under Configure Locales as  Redchillipadi (talk) 02:55, 28 April 2018 (UTC)


 * Fixed (Special:Diff/816541/prev)! For some reason I wasn't seeing it the first time. Thank you! --Maffblaster (talk) 17:23, 25 July 2019 (UTC)

Remind the user to fat32 format the esp partition
I'm a new gentoo user but I guess it's not a bad thing to have a novice's view on how this guide is structured.

The thing I noticed, following the uefi route is that it would be better to get reminded further down again to format sda2 (the esp partition) as FAT32. It isnt mentioned at the appropriate place.

The first time doing this guide, I didn't notice that, ended up installing everything and then the bootloader setup failed because I had the esp as ext2 instead of fat32 (and wasn't able to fix it). Now I'm on my second try due to that.

[...] root #mkfs.ext2 /dev/sda2 root #mkfs.ext4 /dev/sda4 Now create the filesystems on the newly created partitions (or logical volumes)."

It should be placed (or at least mentioned again) here.

AnukWolf (talk) 16:00, 13 October 2018 (UTC


 * While I agree with the partitioning reminder, do yo really believe that it should be included in this section Installing the Gentoo base system? I think it is more appropriate to include an enhancement in Preparing the disks section. There are, to this date, 3 discussions regarding this issue there.--Neyuru (talk) 19:24, 5 April 2020 (UTC)


 * As a new Gentoo user too, I had no problem to use the right filesystem.


 * In the Preparing the disks chapter of 2018 :
 * - The "Using UEFI" section explained all that ; it even emphasized the necessity of a FAT variant for the ESP with a "Important" box, and the risk of not being able to boot otherwise.
 * - The "Default partitioning scheme" section also indicated and summarized the need for FAT32 for the ESP.
 * - The "Applying a filesystem to a partition" section showed the command to create a boot partition in ext2, that's true, but it explicitly stated this was an example (today, this same example is using FAT32, which may be the change you wanted).


 * So, the information is already mentioned 2 times (3 times if you're counting the example), at the appropriate place, and with emphasis.


 * Also, I agree with : there is no use in reminding these things after the Preparing the disks chapter, as the user is supposed to have applied the relevant filesystems to the partitions after that.


 * --Blacki (talk) 07:39, 18 July 2022 (UTC)

Add instructions for bind mounting udev
os-prober needs to function properly and will hang indefinitely if it's not bind mounted from outside. Consider adding a line for bind mounting it from outside the chroot, or at least a small blurb under the mounting to say that other things might need to be mounted. See this section of the GRUB wiki page for details.


 * Thank you for the feedback, . I would like to test on a current LiveCD suggested the change before implementing. --Maffblaster (talk) 18:24, 25 July 2019 (UTC)

Remove command to create /boot
The /boot directory is already present in the stage3 tarball, so `mkdir /boot' can be removed. Also the paragraph just above needs to be adjusted slightly.

--Rafo (talk) 19:02, 1 January 2019 (UTC)


 * Good point. Suggested changes implemented (Special:Diff/816547/prev). Thank you, ! --Maffblaster (talk) 17:53, 25 July 2019 (UTC)

Minor English grammar correction
Where it says, "updates can be delayed after the Gentoo installation has finished," I think it should say "delayed until after." I would change it myself, but I don't have such permissions. --Dhirsbrunner (talk) 03:58, 24 July 2019 (UTC)


 * You got it. I have made the suggested change (see Special:Diff/816511/prev). Thank you for the input! --Maffblaster (talk) 17:06, 25 July 2019 (UTC)

Unclear instructions in section 'Configuring Portage'
In the first subsection 'Installing an ebuild repository snapshot from the web', we tell users that they can skip this subsection if they have no firewalls and a fast network.

But in the second subsection 'Optional: Updating the Gentoo ebuild repository', we don't tell those users that they must run 'emerge --sync', because they skipped 'emerge-webrsync'. Instead, we tell them that 'emerge --sync' is optional. So they might skip this subsection as well and won't have a Gentoo ebuild repository.

--Mike155 (talk) 03:22, 5 November 2019 (UTC)


 * Yes. The  should be the normal and not optional.  Recommending  without the required manual setup as described in Handbook:AMD64/Working/Features is a bad idea.  Better drop it completely or move it to a  .--Charles17 (talk) 08:57, 5 November 2019 (UTC)


 * Can we make this more clear somehow? We just had this same situation play out on IRC. --Sam (talk) 17:57, 15 March 2020 (UTC)


 * Same topic here and there (talk page for »Parts«)--Charles17 (talk) 08:08, 16 March 2020 (UTC)

Incomprehensible sentence: '... as carefully chosen USE flag defaults may be configured in some ebuilds ...'
Do we configure USE flag defaults in ebuilds?

--Mike155 (talk) 18:36, 5 November 2019 (UTC)


 * You are right, it is poorly worded. I have made it more clear. --Maffblaster (talk) 00:21, 6 November 2019 (UTC)

Incomprehensible sentence: '... without prompting the user for the licenses previously accepted.'
The sentence

'Portage uses the ACCEPT_LICENSE variable to determine which packages to allow without prompting the user for the licenses previously accepted.'

doesn't seem to be right. Maybe something like: 'Portage uses the ACCEPT_LICENSE variable to determine which packages are allowed to be installed.'

--Mike155 (talk) 18:36, 5 November 2019 (UTC)

Confusion about per-package exceptions for ACCEPT_LICENSE
One of the first sentences in paragraph 'Optional: Configuring the ACCEPT_LICENSE variable' is: 'Exceptions can be made per-package in /etc/portage/package.license as well.'

The last example of the section shows how to define exceptions in /etc/portage/package.license/kernel.

Why is it etc/portage/package.license in one case and /etc/portage/package.license/kernel in the other? I doubt that new users will understand this.

--Mike155 (talk) 21:24, 5 November 2019 (UTC)


 * This has been clarified in the following diff: Special:Diff/1167615/1169737.

Section 'Configure locales': missing reference to /usr/share/i18n/SUPPORTED
The section tells users that they can/should configure locales in /etc/locale.gen.

The section should also tell users that only locales shown in /usr/share/i18n/SUPPORTED are allowed and that they must pay attention to small and capital letters.

Maybe we can add a box like the one below (I added such a box in the German translation):

--Mike155 (talk) 22:39, 5 November 2019 (UTC)

Hello, this is a welcome enhancement. Thank you for following the recommended format for submitting improvements. I have made the change here. Thank you again! Kind regards, --Maffblaster (talk) 08:06, 6 April 2020 (UTC)

What is an 'rsync tree'?
'News items were created to provide a communication medium to push critical messages to users via the rsync tree.'

What is an 'rsync tree'? Maybe 'Gentoo ebuild tree'?

--Mike155 (talk) 22:27, 6 November 2019 (UTC)


 * This terminology has been removed here Thank you. --Maffblaster (talk) 07:24, 6 April 2020 (UTC)

Add warning about arch-chroot
Some users in #gentoo seeking support run into issues with 'bad file descriptor' after using. We should warn about this and recommend they stick to the given commands.

--Sam (talk) 02:47, 30 March 2020 (UTC)


 * Thank you for the comment however, we cannot provide warnings for all non-recommended software. If someone is having problems using software that is Arch specific (and not available at this time in Gentoo), then they can work that out on the Arch wiki in an Arch bug tracker. We provide instructions to use our official installation media and direction on properly chrooting. Kind regards, --Maffblaster (talk) 07:35, 6 April 2020 (UTC)

Missing locale options for America/Monterrey
Maybe this is a bug of the package and not to be discussed here but, just to inform my findings. I selected the timezone "America/Monterrey" and when configuring the locale with "nano -w /etc/locale.gen" I only found the option: "es_MX ISO-8859-1" in the file, so I selected it (no other option was present for my language). This is dangerous, as the wiki explains: "We strongly suggest to use at least one UTF-8 locale because some applications may require it.". I found out the hard way too: I had several compile time problems when emerging GNOME, which where gone if adding the line "es_MX.UTF-8 UTF-8" to the "/etc/locale.gen" file. Although this option was not present as an option, I can testify that adding it removed the aforementioned compile errors. Can someone help me file this bug?--Neyuru (talk) 03:22, 6 April 2020 (UTC)


 * Hello. Yes, this is not an issue specific to our installation instructions. If you are confident that you have done everything correctly in your installation and you still believe this is an issue with a package, then you'll probably want to file a bug with GNOME's upstream (NOT Gentoo's Bugzilla). If you otherwise have something you believe is necessary to add to these installation instructions, then please follow our recommended format for submitting improvements. Kind regards, --Maffblaster (talk) 07:39, 6 April 2020 (UTC)

Hello and thank you for the rapid response. Yes, I agree there is nothing wrong in the instructions, but I wonder, is the main problem in the omission of the correct encoding options available in "America/Monterrey"? or in GNOME not supporting some encodings? I tend to gravitate to the first option. It is strange that by specifying this locale only *one* of the options belong to the official language spoken there, and it is not even in UTF-8. This is a list of the options available: {#en_US ISO-8859-1, #en_US.UTF-8 UTF-8, #ja_JP.EUC-JP EUC-JP, #ja_JP.UTF-8 UTF-8, #ja_JP EUC-JP, #en_HK ISO-8859-1, #en_PH ISO-8859-1, #de_DE ISO-8859-1, #de_DE@euro ISO-8859-15, #es_MX ISO-8859-1, #fa_IR UTF-8, #fr_FR ISO-8859-1, #fr_FR@euro ISO-8859-15, #it_IT ISO-8859-1}. I sincerely apologize as this conversation does not belong here but, I wanted to share my experience, if someone could find that useful. --Neyuru (talk) 16:50, 7 April 2020 (UTC)


 * Search for /usr/share/i18n/SUPPORTED (has been added lately) in the article. --Charles17 (talk) 17:57, 7 April 2020 (UTC)

Move Selecting Mirrors section after the chroot entry
If a user is not using the Gentoo installation media (and in #gentoo, we often note that it's not necessary to use Gentoo's media), they may not have access to the  tool until they enter the chroot.

Perhaps it should be moved after the chroot section.

--Sam (talk) 01:51, 24 April 2020 (UTC)

The "locale.gen" file doesn't have template like in the handbook base steps
Hi there. During installation of the fresh gentoo, I found that "locale.gen" file from the stage3-amd64-20200607T214504Z doesn't have template like in the handbook steps.

I think that it was good idea, if user can uncomment a language that he needs in the locale.gen file instead of to looking for this language param in the man page of locale!

What do you think about it?

Thanks in advance!

--t0ha (talk) 21:15, 12 June 2020 (UTC)

Use "--changed-use" instead of "--newuse" while updating @world
"--changed-use" is better for daily Gentoo user. "--newuse" leads to unnecessary rebuild of packages which didn't really change since last build.

Recently, the cleanup of ABI_RISCV and related use flags caused rebuild of hundreds of packages, due to the widely use of "--newuse".

Many Gentoo users don't realize the existence of "--changed-use". They just follow the Handbook and keep using "--newuse".

I heard that "--newuse" was put here to remind base system team not to forget revbmp. But since this Handbook is mostly used by new users, maybe we can add a note about the difference between "--changed-use" and "--newuse" at least. And let the user choose which one they want to use.

Imrebuild (talk) 08:54, 17 October 2020 (UTC)

Gnome no longer requires systemd
There are gnome profiles without systemd that use elogind instead. Should the sentence about using >= gnome 3.8 be removed?

Trainz-are-kul (talk) 20:17, 21 November 2020 (UTC)


 * Done --Grknight (talk) 13:15, 22 November 2020 (UTC)

Mounting of btrfs
I often failed with the handbook when it later comes to grub-mkconfig -o /boot/grub/grub.cfg /usr/sbin/grub-probe: error: cannot find a device for / (is /dev mounted?). ...because there is no / in the 'mount' list. I usually do a mount -a inside the chroot in order to mount all the btrfs subvolumes configured in the fstab there. But / wasn't mounted like that. The simple workaround is and please mention that in the handbook: mount / After that / is mounted again from the internal fstab and grub-mkconfig works.

--Massimo B. (talk) 11:55, 15 December 2021 (UTC)


 * Hello,, did you put your btrfs rootfs in a separate, non-default btrfs subvolume? Either that, or I'm wondering if you just didn't   into the chroot... what are the steps for someone to reproduce? If the Handbook is missing a step we'll try to change it, but creating subvolumes is outside Handbook scope... and recursively mounting /dev is already in the Handbook. Thank you, --Maffblaster (talk) 23:13, 20 December 2021 (UTC)


 * Hi, I have the rootfs on a non-default btrfs subvolume, yes. You mean setting it as default would solve the issue? However grub-mkconfig just parses 'mount' for / and doesn't find it. This is my fstab which I just apply by mount -a && mount / after entering the chroot, mount -a alone does not seem to (re)mount /:

grep btrfs /etc/fstab LABEL=gentoo	/				btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes/root			0 1 LABEL=gentoo	/mnt/btrfs-top-lvl		btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=/					0 1 LABEL=gentoo	/home				btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes/home			0 1 LABEL=gentoo	/mnt/data			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes/data			0 1 LABEL=gentoo	/tmp				btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/tmp		0 1 LABEL=gentoo	/usr/portage			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/usr.portage	0 1 LABEL=gentoo	/usr/src			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/usr.src	0 1 LABEL=gentoo	/var/cache			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/var.cache	0 1 LABEL=gentoo	/var/db/repos			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/var.db.repos	0 1 LABEL=gentoo	/var/lib/layman			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/var.lib.layman	0 1 LABEL=gentoo	/var/tmp			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=volumes.root.nosnap/var.tmp	0 1 --Massimo B. (talk) 10:52, 22 December 2021 (UTC)
 * 1) LABEL=gentoo	/mnt/snapshots			btrfs	defaults,compress-force=zstd:3,space_cache=v2,subvol=snapshots				0 1