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.

Steps to build a Gentoo chroot environment:

Create the Gentoo mount point.
```
$ sudo mkdir -p /mnt/gentoo
```
Move into the mount point.
```
$ cd /mnt/gentoo
```

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.

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

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]

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.

Copy the host DNS resolver file into the chroot.

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

Mount /proc inside the chroot.

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

Bind /sys into the chroot.

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

Mark the /sys bind mount recursive slave.

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

Bind /dev into the chroot.

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

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.

Bind /run into the chroot.

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

Mark the /run bind mount slave.

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

Verify the chroot can execute a Gentoo command.

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

Enter the Gentoo chroot.
```
$ sudo chroot /mnt/gentoo /bin/bash
```
Load the Gentoo shell profile.
```
# source /etc/profile
```
Mark the prompt as a chroot shell.
```
# export PS1="(chroot) ${PS1}"
```
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.
Exit the chroot shell when finished.
```
# exit
```

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