How To: Alpine + Sway + Qemu


For a while now I've been wanting to have a setup that involved using Alpine and Sway. Mostly, because I want to build applications on two technologies. Musl and Wayland.

Alpine provides a way to use musl libc without much hassle when building native applications.

Sway provides an up to date Wayland Compositor to test out Wayland Client development with.

Unfortunately, I haven't been able to get Alpine on a laptop yet. I haven't had problems using it with just the terminal in Qemu. So I thought why not try it with Sway. Lets just say that was a no go. The reason being that Wayland is expecting information about a graphics driver. Well if you dont have a graphics card because you are running a VM that becomes a problem. As in Sway wont even start type of a problem.

Luckily this was discussed on Drew Devault's mailing list and a good samaritan provided instructions. The next problem I ran into was I had no idea what qxl was, or how to install a linux virtual kernel, install kernel modules. Lucky me.

So this guide is a way for me to pave the way for others to walk down more easily.

NOTE: Only tested for x86 architecture.


The first major step we have to overcome is building Qemu from source with SPICE enabled. SPICE is a protocol that allows remote viewing of machines with graphics. I'll show you how to do this on Debian because that's what I used.

Download the latest QEMU source code here.

Spice packages

Before we can compile we must install the spice libraries.

sudo apt install libspice-protocol-dev libspice-server-dev pkg-config libglib2.0-dev libpixman-1-dev libncurses-dev


Then compile the source code after unpackaging it.

tar -xf qemu-5.1.0.tar.xz
cd qemu-5.1.0
./configure --enable-spice --target-list=x86_64-softmmu

A note on the configuring. Notice I'm specifying the build target to be x86_64 because that's all I care about for now, and this significantly speeds up compilation time. You can either delete this flag to build all architectures, or add the other specific architectures.

To install it:

sudo make install

Now you will have the qemu-system-x86_64 binary available.


Before we can utilize this spice enabled qemu we must install the SPICE client.

sudo apt install virt-viewer

This installs the virt-viewer package but we will be using the remote-viewer binary. Something that tripped me up.

Create Image

We need to create the image to install the OS on.

 qemu-img create -f qcow2 alpine.qcow2 16G

This creates an image with qcow2 format and 16G disk space. Don't worry this will only use what it needs, not reserve space for 16G of disk.

Download the Alpine Standard Iso from here.

Now with the Alpine Standard Iso we downloaded earlier, we are going to install Alpine on the image we just created.

qemu-system-x86_64 \
    -enable-kvm \
    -m 2048 \
    -nic user,model=virtio \
    -drive file=alpine.qcow2,media=disk,if=virtio \
    -cdrom alpine-standard-3.12.0-x86_64.iso \
    -display curses

This will go through the install process with curses mode. The installer is pretty straight forward.

Run setup-alpine and follow most of the defaults.

When it asks about disk, make sure to choose vda and then choose sys for the type.

After this completes you can shut it down.

Connect VM to Spice Client

Here is how to run the QEMU VM with qxl/spice enabled.

qemu-system-x86_64 -machine vmport=off \
    -enable-kvm \
    -m 2048 \
    -boot order=dc -vga qxl \
    -spice port=3001,disable-ticketing \
    -device intel-hda -device hda-duplex \
    -device virtio-serial -chardev spicevmc,id=vdagent,debug=0,name=vdagent \
    -device virtserialport,chardev=vdagent,name=com.redhat.spice.0 \

I stole the above monstrosity from the Spice User Manual. I highly recommend putting that in a little script.

In fact I have a repo with all of the above as scripts that you can find here.

Now in another terminal we run the client.

remote-viewer spice://localhost:3001

You should see the OS boot up.

More Alpine Stuff

Before we can get Sway running we need to prepare Alpine with proper packages and kernel modules.

apk add linux-virt

To get this kernel to be used it is easiest to simply delete the old one.

apk del linux-lts

Then reboot. Once you've rebooted check that it is using the virtual kernel.

uname -r

Once it is back up we need to edit some files.

sudo nano /etc/modprobe.d/kms.conf

Add these lines to the bottom of the file.

options bochs_drm modeset=1
options qxl modeset=1

Now we edit this file.

sudo nano /etc/modules

Add these two lines.


Once again we have to reboot for these changes to take effect.


Wayland seems to not be able to start easily on non SystemD distros. The work around for this is to use elogind. This package is still in the edge community repo. So make sure to enable that in /etc/apk/repositories.

apk update
apk add elogind

Now make sure you have a user that you can login to besides root.

adduser *username*

Add them to video and input groups.

adduser *username* video
adduser *username* input

When we eventually run Sway we will need to be logged into username.

For now lets finish installing the necessary packages.

apk add eudev

# This is the graphics driver we will need for guest
apk add mesa-dri-gallium

#This is needed to populate /usr/share/X11/xkb
apk add xkeyboard-config

apk add libinput font-noto

Then finally install sway and friends.

apk add sway alacritty

This will give you a super minimalist OS that can only run wayland apps. To use apps that require X.Org then install xwayland-server. Personally I like not having it because I get to try out apps and see if they work with Wayland natively.


This is the moment we've been waiting for a working Sway installation inside of Qemu.

Make sure you are logged into a username. Reboot if you have if you must, because this is important. elogind will not work without this, and then no sway.

After logging in, run Sway.

XDG_RUNTIME_DIR=/tmp sway 2> sway.log

This will output error logs in case something goes wrong.

Happy coding with Wayland!

More Posts