How to build a Gentoo chroot environment

Building a Gentoo chroot lets a host prepare, repair, or test a Gentoo userland without booting it directly. The chroot only works when the stage3 files, DNS resolver, and kernel-backed filesystems match what Gentoo expects, otherwise Portage and shell startup checks can fail with misleading dev or resolver errors.

An AMD64 OpenRC chroot starts from the current stage3 manifest in Gentoo's autobuilds directory. The archive must be extracted with the extended-attribute and numeric-owner flags expected by the Handbook, then the host's /proc, /sys, /dev, and /run filesystems must be exposed to the new root. A systemd chroot uses the matching systemd stage3 manifest, but the mount propagation steps are still required before runtime tools can behave normally.

After entry, the shell should report a Gentoo base release from inside /mnt/gentoo, and Portage should have a repository snapshot before package work begins. Profile selection, locale generation, kernel setup, and bootloader installation belong after the chroot itself is available.

1. Create the Gentoo mount point.

   $ sudo mkdir -p /mnt/gentoo

2. Move into the mount point.

   $ cd /mnt/gentoo

3. Download the current AMD64 OpenRC stage3 manifest.

   $ wget https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-openrc/latest-stage3-amd64-openrc.txt
   2026-06-11 03:34:27 URL:https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-openrc/latest-stage3-amd64-openrc.txt [691/691] -> "latest-stage3-amd64-openrc.txt" [1]

   Use the matching current-stage3-amd64-systemd directory instead when the target chroot will use systemd.

4. Select the stage3 tarball named in the manifest.

   $ STAGE3=$(awk '/^stage3-amd64-openrc-.*[.]tar[.]xz / {print $1; exit}' latest-stage3-amd64-openrc.txt)
   $ printf '%s\n' "$STAGE3"
   stage3-amd64-openrc-20260610T214636Z.tar.xz

5. Download the selected stage3 tarball.

   $ wget "https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-openrc/$STAGE3"
   2026-06-11 03:34:55 URL:https://distfiles.gentoo.org/releases/amd64/autobuilds/current-stage3-amd64-openrc/stage3-amd64-openrc-20260610T214636Z.tar.xz [300282916/300282916] -> "stage3-amd64-openrc-20260610T214636Z.tar.xz" [1]

6. Extract the stage3 archive into /mnt/gentoo.

   $ sudo tar xpvf "$STAGE3" --xattrs-include='*.*' --numeric-owner -C /mnt/gentoo
   ./
   ./bin/
   ./boot/
   ./dev/
   ./etc/
   ##### snipped #####

   The --xattrs-include='*.*' and --numeric-owner flags preserve the metadata Gentoo release engineering put into the stage3 archive.

7. Copy the host DNS resolver file into the chroot.

   $ sudo cp --dereference /etc/resolv.conf /mnt/gentoo/etc/

8. Mount /proc inside the chroot.

   $ sudo mount --types proc /proc /mnt/gentoo/proc

9. Bind /sys into the chroot.

   $ sudo mount --rbind /sys /mnt/gentoo/sys

10. Mark the /sys bind mount recursive slave.

    $ sudo mount --make-rslave /mnt/gentoo/sys

11. Bind /dev into the chroot.

    $ sudo mount --rbind /dev /mnt/gentoo/dev

12. Mark the /dev bind mount recursive slave.

    $ sudo mount --make-rslave /mnt/gentoo/dev

    On some non-Gentoo live systems, /dev/shm may point into /run in a way that breaks after chroot entry. Fix /dev/shm before continuing if shell or Portage commands report broken /dev/fd or /dev/shm.

13. Bind /run into the chroot.

    $ sudo mount --bind /run /mnt/gentoo/run

14. Mark the /run bind mount slave.

    $ sudo mount --make-slave /mnt/gentoo/run

15. Verify the chroot can execute a Gentoo command.

    $ sudo chroot /mnt/gentoo cat /etc/gentoo-release
    Gentoo Base System release 2.18

16. Enter the Gentoo chroot.

    $ sudo chroot /mnt/gentoo /bin/bash

17. Load the Gentoo shell profile.

    # source /etc/profile

18. Mark the prompt as a chroot shell.

    # export PS1="(chroot) ${PS1}"

19. Install the initial Gentoo ebuild repository snapshot.

    # emerge-webrsync

    The snapshot gives Portage a current package repository. A later emerge --sync can refresh it through rsync after the chroot is working.

20. Exit the chroot shell when finished.

    # exit

21. Unmount the runtime filesystems from the host.

    $ sudo umount -R /mnt/gentoo/run
    $ sudo umount -R /mnt/gentoo/dev
    $ sudo umount -R /mnt/gentoo/sys
    $ sudo umount /mnt/gentoo/proc