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.
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 DeveloperWiki:Building in a Clean Chroot.
See also Wikipedia:Chroot#Limitations.
- 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/sdxY
- Internet connection established if needed.
There are two main options for using chroot, described below.
The bash script
arch-chroot is part of the package. Before it runs
/usr/bin/chroot, the script mounts api filesystems like
/proc and makes
/etc/resolv.conf 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
# arch-chroot /mnt
To exit the chroot simply use:
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
mkinitcpio -p linux for a chroot located at
# arch-chroot /mnt/arch mkinitcpio -p linux
In the following example /location/of/new/root 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 --rbind /sys sys/ # mount --rbind /dev dev/
# mount --rbind /run run/
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 /location/of/new/root 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
When finished with the chroot, you can exit it via:
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:
$ 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 in the chroot environment run
# 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 may be used to change the apparent root directory and use
mount --bind 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
--root-id argument that can be used as a workaround for some of these limitations in a similar (albeit more limited) manner to fakeroot.
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