Creating Arch Linux disk image

From ArchWiki
Revision as of 20:17, 8 May 2012 by Synchronicity (talk | contribs) (Other tips)
Jump to: navigation, search

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

This page describes how to create a file that contains a disk image of Arch Linux, so that it can be run in a virtual machine using software such as QEMU, VirtualBox, or VMware. This disk image can be customized however you want.


The official installation media for Arch Linux is a hybrid ISO/disk image, so it can already be booted either as a CD-ROM or as a disk. However, it uses an ISO filesystem, so nothing on it can be changed without re-making the installation media.

You can also create your own live Arch Linux systems using the Archiso tools. This may be what you want, but Archiso is only designed for building live systems that boot from a read-only filesystem.

Installing Arch Linux in a disk image using the installation media

Using QEMU, VirtualBox, or other virtualization software, you can install Arch Linux into a disk image by booting the virtual machine from the installation media. This is the preferred way to make a virtual disk image containing Arch Linux because other than starting up the virtual machine, the installation will proceed exactly as in the Official Installation Guide.

Install Arch Linux in a disk image without the installation media

It is also possible to create a disk image of Arch Linux directly from software and packages on a host Arch Linux system. This has a couple of advantages:

  • You do not need to have a copy of the installation media.
  • You can include the most up-to-date software packages in the disk image by installing them directly from the host's package manager before the virtual machine is even running.
  • You can customize the disk image in ways that may not be supported by the official Arch Linux installer.

However, this method is more difficult than using the installation media.

In these directions, the host system refers to the Arch Linux system you are currently running, while the guest system refers to the Arch Linux system you are creating as a disk image.

Make a file containing the disk image

  • Create a raw disk image for the virtual machine. In this example, it is made with a size of 1 GiB.
$ dd if=/dev/zero bs=1024 count=262144 of=archlinux.raw

Or, on filesystems supporting the fallocate() system call:

$ fallocate -l 1G archlinux.raw
  • If you have installed QEMU, you may also use qemu-img create, or even use a non-raw format such as qcow2, provided that you export it using qemu-nbd so that you can get the actual disk image as a loopback device.

Partition the disk image and create filesystems

You can partition the disk image however you want. In this simple example, it will be given only one partition, that will be a primary partition and contain an ext4 filesystem containing all of /boot, /home, and /. There will be no swap partition.

  • Partition the disk.
$ fdisk archlinux.raw <<< '
$ > o
$ > n
$ >
$ >
$ >
$ >
$ > w'
  • Make the partitions available as loopback devices. The rest of the instructions will assume that the loopback device created for archlinux.raw is /dev/loop0, but it will be a higher number if you already have set up loop devices.
# losetup -f --show archlinux.raw
# kpartx -a /dev/loop0
Note: kpartx is part of the multipath-tools package. See QEMU#Mounting_a_partition_inside_a_raw_disk_image for other ways to mount a partition inside a disk image. But beware: GRUB2 will not install correctly to the disk image unless the partition loopback device is created through the device mapper (using kpartx)
  • Make the needed filesystems on the partitions.
# mkfs -t ext4 /dev/mapper/loop0p1

Install packages on the guest's filesystem

  • Mount the guest's root filesystem on a temporary directory.
# TMPDIR=/full/path/to/temporary/directory
# mount /dev/mapper/loop0p1 $TMPDIR
  • Create a directory that pacman needs.
# mkdir -p $TMPDIR/var/lib/pacman/sync
  • Synchronize the package databases on the host system.
# pacman -Sy
  • Copy package databases to the guest's filesystem.
# cp /var/lib/pacman/sync/*  $TMPDIR/var/lib/pacman/sync
  • Install packages using the guest's filesystem as an alternative installation root. You can install whatever packages you want, and anything that is in the package cache on the host system is not re-downloaded. A good idea would be to install the base system, although not everything in it is actually needed:
# pacman --root $TMPDIR -S base

You definitely will need essential packages such as linux and initscripts. Note that the post-installation hooks for linux will fail because /proc, /sys, and /dev are not mounted inside the guest. We will generate the initramfs later.

Edit configuration files for the guest

  • Add any mountpoints to the guest's fstab file. In this example, we just need a mountpoint for the guest's root filesystem. Here we specify it by UUID, although you could also just use /dev/sda1, provided that that's what it will appear as when you run the virtual machine.
# UUID=$(blkid -s UUID -o value /dev/mapper/loop5p1)
# echo "UUID=$UUID   /   ext4   defaults   0   1" >> $TMPDIR/etc/fstab 
  • You may need to edit $TMPDIR/etc/rc.conf, although in this example the guest will boot with the default values.
  • You may need to edit $TMPDIR/etc/mkinitcpio.conf to remove the autodetect hook, to stop your host system's hardware configuration from removing essential modules from the initramfs of the guest, which is going to be running in a different environment in a virtual machine.

Generate initramfs for the guest

As noted earlier, initramfs generation failed when installing linux. Generate the initramfs for the guest manually by running the following command:

# mkinitcpio -g $TMPDIR/boot/initramfs-linux.img -k $TMPDIR/boot/vmlinuz-linux -c $TMPDIR/etc/mkinitcpio.conf

Install bootloader on the guest

In this example, we will install the GRUB2 bootloader on the guest. Make sure you have grub2-bios installed on the host system.

  • Install GRUB. --boot-directory must be set to the /boot directory within the guest's root filesystem, while the given device must be the loopback device corresponding to the guest's entire disk image. Be careful not to overwrite the bootloader of your host system!
# grub-install --boot-directory=$TMPDIR/boot /dev/loop0
  • Write a grub.cfg file. Replace $UUID, in both places, with the UUID of the guest's root filesystem, which was set to the variable $UUID above.
set default="0"
set timeout="3"
insmod msdos
insmod ext4
set root='(/dev/sda, msdos1)'
search --no-floppy --fs-uuid --set=root $UUID
menuentry "Arch Linux" {
   linux /vmlinuz-linux root=/dev/disk/by-uuid/$UUID ro
   initrd /initramfs-linux.img


You should not boot the guest while its filesystem is still mounted; otherwise, the files on it may be corrupted. Unmount the guest's filesystem and get rid of the loopback devices first.

# umount $TMPDIR
# kpartx -d /dev/loop0
# losetup -d /dev/loop0

Boot the guest

Finally, boot the guest Arch Linux using your virtualization software of choice, such as QEMU:

# qemu archlinux.raw

Other tips

  • If you use QEMU, you can specify the guest's kernel and initramfs on the command line. This means that you can avoid having a partitioned disk image with a bootloader entirely, and just have a raw filesystem image containing the root filesystem.
  • Since you have full control over the guest's hardware, it is not too hard to skip installing the linux package and install compile a custom kernel for the guest that has all the needed modules built in, if you are familiar with configuring the Linux kernel.
  • You can make copies of your disk image and run multiple Arch Linux virtual machines at the same time.
  • See Install from Existing Linux for some more general tips about installing Arch Linux from an existing Linux installation (that doesn't necessarily have to be Arch Linux).