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.

See also Wikipedia:Chroot#Limitations.

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 , 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

Note: If there is an error mentioning something like umount: /path: device is busy, this usually means that either: a program (even a shell) was left running in the chroot or that a sub-mount still exists. Quit the program and use findmnt -R /location/of/new/root to find and then umount sub-mounts. It may be tricky to umount some things and one can hopefully have umount --force work. As a last resort, use umount --lazy which just releases them. In either case to be safe, reboot as soon as possible if these are unresolved to avoid possible future conflicts.

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 , 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.

See also

• Basic Chroot