chroot

A chroot is an operation that changes the apparent root directory for the current running process and their children. A program that is run in such a modified environment cannot access files and commands outside that environmental directory tree. This modified environment is called a chroot jail.

Reasoning

Changing root is commonly done for performing system maintenance on systems where booting and/or logging in is no longer possible. Common examples are:

Reinstalling the bootloader.
Rebuilding the initramfs image.
Upgrading or downgrading packages.
Resetting a forgotten password.
Building packages in a clean chroot.

Requirements

Root privilege.
Another Linux environment, e.g. a LiveCD or USB flash media, or from another existing Linux distribution.
Matching architecture environments; i.e. the chroot from and chroot to. The architecture of the current environment can be discovered with: uname -m (e.g. i686 or x86_64).
Kernel modules loaded that are needed in the chroot environment.
Swap enabled if needed:
```
# swapon /dev/sd''xY''
```
Internet connection established if needed.

Usage

Note:

Some systemd tools such as hostnamectl, localectl and timedatectl can not be used inside a chroot, as they require an active dbus connection.
The file system that will serve as the new root (/) of your chroot must be accessible (i.e., decrypted, mounted).

There are two main options for using chroot, described below.

Using arch-chroot

The bash script is part of the package. Before it runs , the script mounts API filesystems like and makes available from the chroot.

Enter a chroot

Run arch-chroot with the new root directory as first argument:

# arch-chroot /location/of/new/root

For example, in the installation guide, this directory would be /mnt:

# arch-chroot /mnt

To exit the chroot, simply use:

# exit

Chrooting into an existing installation

Run and note the partition layout of your installation. It will be usually something like or if you have an NVMe drive .

Mount the file system:

# mount /dev/sdXY /mnt

Additionally, if you have an EFI system partition and need to make changes in it (e.g. updating the vmlinuz or initramfs images):

# mount /dev/sdXZ /mnt/esp

Finally, enter the chroot:

# arch-chroot /mnt

To exit the chroot, use:

# exit

You can now do most of the operations available from your existing installation. Some tasks which needs D-Bus will not work as noted in #Usage.

Run a single command and exit

To run a command from the chroot and exit again, append the command to the end of the line:

# arch-chroot /location/of/new/root mycommand

For example, to run for a chroot located at /mnt/arch, do:

# arch-chroot /mnt/arch mkinitcpio -p linux

Using chroot

In the following example, is the directory where the new root resides.

First, mount the temporary API filesystems:

# cd /location/of/new/root
# mount -t proc /proc proc/
# mount -t sysfs /sys sys/
# mount --rbind /dev dev/

And optionally:

# mount --rbind /run run/

If you are running a UEFI system, you will also need access to EFI variables. Otherwise, when installing GRUB, you will receive a message similar to: :

# mount --rbind /sys/firmware/efi/efivars sys/firmware/efi/efivars/

Next, in order to use an internet connection in the chroot environment, copy over the DNS details:

# cp /etc/resolv.conf etc/resolv.conf

Finally, to change root into using a bash shell:

# chroot /location/of/new/root /bin/bash

After chrooting, it may be necessary to load the local bash configuration:

# source /etc/profile
# source ~/.bashrc

Tip: Optionally, create a unique prompt to be able to differentiate your chroot environment:

# export PS1="(chroot) $PS1"

When finished with the chroot, you can exit it via:

# exit

Then unmount the temporary file systems:

# cd /
# umount --recursive /location/of/new/root

Run graphical applications from chroot

If you have an X server running on your system, you can start graphical applications from the chroot environment.

To allow the chroot environment to connect to an X server, open a virtual terminal inside the X server (i.e. inside the desktop of the user that is currently logged in), then run the xhost command, which gives permission to anyone to connect to the user's X server (see also Xhost):

$ xhost +local:

Then, to direct the applications to the X server from chroot, set the DISPLAY environment variable inside the chroot to match the DISPLAY variable of the user that owns the X server. So for example, run:

$ echo $DISPLAY

as the user that owns the X server to see the value of DISPLAY. If the value is ":0" (for example), then run the following in the chroot environment:

# export DISPLAY=:0

Without root privileges

Chroot requires root privileges, which may not be desirable or possible for the user to obtain in certain situations. There are, however, various ways to simulate chroot-like behavior using alternative implementations.

PRoot

PRoot may be used to change the apparent root directory and use without root privileges. This is useful for confining applications to a single directory or running programs built for a different CPU architecture, but it has limitations due to the fact that all files are owned by the user on the host system. PRoot provides a argument that can be used as a workaround for some of these limitations in a similar (albeit more limited) manner to fakeroot.

Fakechroot

is a library shim which intercepts the chroot call and fakes the results. It can be used in conjunction with  to simulate a chroot as a regular user.

$ fakechroot fakeroot chroot ~/my-chroot bash

Unshare

Unshare, part of , can be used to create a new kernel namespace. This works with the usual chroot command. For example:

$ unshare --map-root-user chroot ~/namespace /bin/sh

Troubleshooting

arch-chroot: /location/of/new/root is not a mountpoint. This may have undesirable side effects.

Upon executing arch-chroot /location/of/new/root, a warning is issued:

==> WARNING: /location/of/new/root is not a mountpoint. This may have undesirable side effects.

See for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.