Script to automate the management of Arch Linux qemu-based VMs
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

3.8 KiB


vmctl is a script that automates the installation, provisioning and management of Arch Linux virtual machines.


  • qemu
  • curl
  • expect


Just copy the vmctl script anywhere in your PATH, or clone the repository and create a symbolic link to vmctl in your PATH.


Install an Arch Linux virtual machine

The vmctl install command can be used to create an Arch Linux virtual machine on the fly, wherever you are. It does the following:

  • It downloads the latest Arch Linux installer ISO image if none was downloaded or a new one is available.
  • It creates a qemu disk file.
  • It boots a new KVM that uses the ISO file as as CDROM and automates the installation of Arch Linux in the virtual machine (no user prompt required).
  • It can install extra packages and run custom post-installation provisioning scripts.
Usage: vmctl install [-o <output-disk-image>] [-a <architecture>] [-s <disk-size>]
        [-m <memory>] [-h <hostname>] [-P <root-password>] [-u <non-root-username>]
        [-p <non-root-user-password>] [-z <timezone>] [-l <locale>] [-M <arch-mirror-url>]
        [-K] [extra qemu arguments]

-o      <output-disk-image>             Path of the output disk image (default: ./arch.img)
-a      <architecture>                  Target architecture (default: x86_64)
-s      <disk-size>                     Disk size (default: 8G)
-m      <memory>                        RAM size in KB (default: 2048)
-h      <hostname>                      VM hostname (default: qemu)
-P      <root-password>                 Root password. If not specified it will be prompted
-u      <non-root-username>             Username for the main non-root user
-p      <non-root-user-password>        Password for the non-root user. If not specified it will be prompted
-z      <timezone>                      System timezone (default: UTC)
-l      <locale>                        System locale (default: en_US.UTF-8)
-M      <arch-mirror-url>               Arch Linux download mirror URL (default:
                                        Consult for a full list of the available download mirrors.
-K                                      Disable pacman keyring checks during installation. It's potentially unsafe,
                                        but it can be an option if downloading the keys takes too long.

If a required option is not specified on the command line then it will be interactively prompted to the user (defaults are available for most of the options).

Non-interactive example:

vmctl install \
    -h my_vm \
    -a x86_64 \
    -s 16G \
    -m 2048 \
    -P root \
    -u myuser \
    -p password \
    -z Europe/Amsterdam \
    -o arch-base.img

If you want to install an extra list of packages besides the default ones, then specify them in a file named PKGLIST in the same directory as the disk image file.

If you want to run a custom post-installation script after the core system has been installed, then create a custom script named in the same directory as the disk image file.


The keyring population process may currently (as of March 2022) take a long time. This is a known issue.

Resize an existing image

qemu-img resize "$imgfile" +10G

Create a COW (Copy-On-Write) image on top of a disk image

qemu-img create -o backing_file="$imgfile",backing_fmt=raw -f qcow2 img1.cow

This is particularly useful if you want to have a "base" image and several customized images built on it.

Convert a raw qemu image to a VirtualBox

qemu-img convert -O vdi disk.img disk.vdi