Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build custom Alpine Linux images with Docker.

Go CI Go Reference

Introduction video


This projects builds custom Alpine Linux images with the alpine-make-vm-image utility, but it uses Docker and a simplified interface so that it can run easily on systems other than Alpine Linux that support Docker, such as for example macOS or other Linux distros.


Binaries are built weekly and uploaded to GitHub releases.

On Linux, you can install them like so:

$ curl -L -o /tmp/alpimager$(uname -m)
$ sudo install /tmp/alpimager /usr/local/bin

On macOS, you can use the following to install:

$ curl -L -o /tmp/alpimager$(uname -m)
$ sudo install /tmp/alpimager /usr/local/bin

On Windows, the following should work (using PowerShell as administrator):

PS> Invoke-WebRequest -OutFile \Windows\System32\alpimager.exe

Note that the Windows builds are broken due to a change in how WSL works; it is no longer supported since WSL2, the new Docker backend in Windows, uses a Kernel without nbd support. If you just want a quick Alpine VM on Windows, I recommend using Alpine WSL instead until Microsoft resolve the issue.


See testdata for example files.

$ alpimager --help
Usage of alpimager:
  -maximumDiskSize string
        Maximum disk size (default "20G")
  -output string
        Output image file (default "alpine.qcow2")
  -packages string
        Package list file (default "packages.txt")
  -repositories string
        Repository list file (default "repositories.txt")
  -script string
        Setup script file (default "")
        Enable verbose logging


  • If you get an error like ERROR: No available nbd device found!, run sudo modprobe nbd on the Docker host.
  • Running alpimager with -verbose might give you more debugging output.


alpimager (c) 2021 Felicitas Pojtinger

SPDX-License-Identifier: AGPL-3.0