Alpine Linux keeps coming up in homelab forums for one reason: it's small. The "virtual" install ISO is around 150 MB, boots to a login prompt in a few seconds, and idles comfortably in 256 MB of RAM. If you've been building Ubuntu or Debian VMs in Proxmox VE and you want something that starts almost instantly without eating into your ZFS pool, Alpine is worth the twenty minutes it takes to set one up.
This guide walks through creating a real Alpine Linux virtual machine in Proxmox VE — not an LXC container, an actual VM with its own kernel — from grabbing the right ISO through installing the QEMU Guest Agent so Proxmox can actually see the VM's IP address. None of this is hard, but Alpine's installer works nothing like Ubuntu's, and a couple of its defaults will catch you off guard if nobody warns you first.
What You Will Learn
- How Alpine differs from the Ubuntu or Debian VMs you're probably used to
- Which of Alpine's three ISO variants to actually download
- How to size a VM for something this lightweight
- How to get through
setup-alpine, Alpine's install wizard, without guessing at prompts - How to install the QEMU Guest Agent afterward, since Alpine doesn't ship with it
- The handful of problems almost everyone hits on their first Alpine VM
What Is This Feature?
Alpine Linux is a Linux distribution built on musl libc and BusyBox instead of the glibc and GNU userland most distros use. That's a technical detail, but it's the reason the install ISO is 150 MB while a minimal Ubuntu Server ISO runs closer to 1.5 GB. Alpine ships with a shell, a package manager, and not much else. An SSH server, Python, even a text editor beyond vi — you add all of it deliberately with apk, short for Alpine Package Keeper.
It also runs OpenRC instead of systemd for managing services. If you've only ever used Ubuntu, Debian, or Fedora, that's the adjustment that trips people up first: systemctl status doesn't exist here. You'll use rc-service and rc-update instead. We'll cover both when we get to the guest agent install.
Why Would You Use It?
Nobody needs Alpine as a general-purpose desktop replacement, and that's not what it's for. Where it earns its keep is anywhere you want a VM that does one small job and stays out of the way: a DNS resolver, a lightweight reverse proxy, a cron box for a couple of scripts, or a throwaway VM for testing something against musl instead of glibc (some software behaves differently on the two, and Alpine is the easiest way to find out before it surprises you in production).
It's also a good fit if you're running Proxmox on modest hardware — an old N100 mini PC, a repurposed laptop, a Raspberry Pi cluster — where every extra 500 MB of RAM matters. A minimal Alpine VM idling at rest uses a fraction of what an equivalent Ubuntu Server install needs.
Prerequisites
You'll need a working Proxmox VE 8.x or 9.x host with at least one storage location that accepts ISO images, and enough free space for a small virtual disk — 2 to 4 GB is plenty for most Alpine use cases. You don't need any Alpine experience going in. Basic comfort creating a VM in the Proxmox web interface helps, but every screen is covered below.
Grab the ISO before you start. Head to alpinelinux.org/downloads and look for the virtual edition under x86_64. Alpine actually publishes three ISO flavors, and picking the wrong one is the single most common mistake people make:
| ISO Flavor | Size | Use it when… |
|---|---|---|
| virtual | ~150 MB | Installing inside a VM (this guide). Ships with VirtIO drivers baked in and skips firmware for physical hardware you don't have. |
| standard | ~250 MB | Installing on real hardware, since it includes firmware for physical NICs, Wi-Fi, and so on. |
| extended | ~950 MB | You want a fuller package set available offline, without pulling from the network during setup. |
For a Proxmox VM, virtual is the right choice every time. At the time of writing the current stable branch is 3.21.x, but these steps hold up fine on 3.19 or 3.22 too — Alpine's installer hasn't changed shape in years.
Step-by-Step Tutorial
1. Upload the ISO to Proxmox
In the Proxmox web UI, click your storage that has ISO Image enabled under Datacenter → Storage (usually local), open the ISO Images tab, and click Upload. Point it at the alpine-virt-3.21.x-x86_64.iso file you downloaded. On a decent connection this takes well under a minute since the file is so small.
2. Create the virtual machine
Click Create VM in the top right. On the General tab, give it a name like alpine-test and note the VMID Proxmox assigns.
On the OS tab, select your uploaded ISO and set Linux as the guest OS type, kernel version 6.x - 2.6 Kernel. On the System tab, leave the defaults (SeaBIOS, i440fx) unless you specifically need UEFI — Alpine doesn't require it, and SeaBIOS boots slightly faster for a VM this small. Tick Qemu Agent now; we'll install the agent inside the VM in a later step, but flipping this checkbox now saves you a trip back here.
3. Configure the disk and hardware
On the Disks tab, set the bus to SCSI with VirtIO SCSI single as the controller, and size it at 2–4 GB — a base Alpine install with a few packages added uses well under 1 GB. Tick Discard if your underlying storage supports thin provisioning (ZFS and LVM-thin both do); it lets the VM tell Proxmox when space has actually been freed instead of the disk file only ever growing.
On CPU, one core is genuinely enough for most Alpine VMs. On Memory, set 512 MB with the Ballooning Device option left on — Alpine will run comfortably in far less than a typical Ubuntu VM needs. On Network, leave the model at VirtIO (paravirtualized); the virtual ISO already includes the driver for it, so there's nothing extra to install later.
4. Boot the installer
Finish the wizard, select the VM, and click Start, then open the Console. Alpine boots to a login prompt in a few seconds — log in as root with no password, then run:
setup-alpineThis one command is Alpine's entire installer. There's no graphical partitioner, no separate "try before you install" mode — just a series of questions asked directly in the terminal.
5. Answer the setup-alpine prompts
The wizard asks roughly a dozen questions in order. Here's what each one means and what to answer for a typical Proxmox VM:
- Keyboard layout: type your layout (e.g.
us), then confirm the variant. - Hostname: whatever you want the VM to call itself.
- Network interface: answer
eth0, thendhcpunless you already have a static IP plan — you can convert to static later by editing/etc/network/interfaces. - Manual network configuration: answer
nif you chose DHCP. - Root password: set a real one. This matters more than it sounds — Alpine's root account is fully active from first boot, unlike Ubuntu, which disables it by default.
- Timezone: e.g.
America/New_York, orUTCif you'd rather keep every VM on the same clock. - Proxy: answer
noneunless your network actually requires one. - NTP client:
chronyis the sane default. - APK mirror: type
fto let Alpine pick the fastest one automatically. - SSH server:
opensshis what you want almost every time. - Allow root login over SSH: the wizard will ask this as part of the SSH setup. Answer
yesfor now if this is a quick test VM; for anything you're keeping, answerprohibit-passwordso root can only log in with a key, never a password. - Disk to use:
sda— it'll be the only one listed. - How to use the disk: answer
sys. This installs Alpine to the disk like a normal OS. The other two options,dataandnone, are for different use cases (data-only partitions, or a RAM-only diskless boot) that don't apply here.
Confirm the last prompt and Alpine writes itself to disk. This takes maybe 30 seconds — there's very little to copy.
6. Reboot and remove the ISO
Once it's done, run reboot, but don't let it boot back into the installer. In the Proxmox UI, go to Hardware, click the CD/DVD drive, and set it to Do not use any media. This is the step people skip, and skipping it is exactly why some Alpine VMs appear to hang forever at a blank prompt after install — it's not actually hung, it's booted back into the live installer environment and is sitting there waiting for you to run setup-alpine all over again.
7. Log in and enable the community repository
Log back in as root with the password you set. Alpine's package repositories are split into main (core, officially supported) and community (everything else, including a lot of packages you'll actually want). Open the repo file:
vi /etc/apk/repositoriesMake sure the community line for your version is uncommented — no # in front of it — then update your package index:
apk update8. Install the QEMU Guest Agent
This is the step that actually connects the VM to Proxmox's monitoring — without it, Proxmox has no idea what IP address the VM has, and the "Shutdown" button in the UI does a hard power-off instead of a clean shutdown.
apk add qemu-guest-agent
rc-update add qemu-guest-agent default
rc-service qemu-guest-agent startThe first line installs the agent package. The second tells OpenRC to start it automatically at every boot from now on (the OpenRC equivalent of systemctl enable). The third starts it immediately, so you don't have to reboot to see it working.
9. Confirm it's working
Click your VM in Proxmox and open the Summary tab. Within a few seconds you should see an IP address show up under IPs. If it doesn't appear, double-check that you ticked Qemu Agent back in step 2 — if you missed it, go to Options → QEMU Guest Agent and enable it there, no reboot of the VM config required, just a VM restart.
Commands Explained
| Command | What it does |
|---|---|
setup-alpine | Alpine's entire text-based installer — keyboard, network, users, disk, all of it in one wizard. |
apk update | Refreshes the local package index from the mirrors listed in /etc/apk/repositories. |
apk add <package> | Installs a package. There's no separate "install" vs "search" command set like apt has — apk search <name> covers that. |
rc-update add <service> default | OpenRC's equivalent of systemctl enable — adds a service to the "default" runlevel so it starts at boot. |
rc-service <service> start | Starts a service immediately, equivalent to systemctl start. |
Common Errors
"ERROR: unsatisfiable constraints" when running apk add for something like bash or sudo almost always means the community repository is still commented out in /etc/apk/repositories. Fix the file, run apk update again, and retry.
VM appears frozen after install, showing a boot menu or a plain prompt that never changes. This is the CD/DVD drive issue from step 6 — the VM booted the installer ISO again instead of the disk. Detach the ISO and reboot.
No IP address shown in the Proxmox Summary tab even after installing the guest agent. Check that the service actually started with rc-service qemu-guest-agent status, and confirm the Qemu Agent checkbox is ticked under the VM's Options tab. Both need to be true at once.
Locked out over SSH after answering "no" to root login during setup. If you didn't create a second user during setup-alpine and disabled root SSH access, your only way in is the Proxmox console. Log in there, edit /etc/ssh/sshd_config, and either re-enable root login temporarily or create a regular user with adduser.
Troubleshooting
If networking doesn't come up after boot — no DHCP lease, no connectivity — the console is your friend. Run ifconfig eth0 to confirm the interface has an address at all. If it shows no IP, check cat /etc/network/interfaces; Alpine uses the classic ifupdown-style config, so you're looking for a stanza like:
auto eth0
iface eth0 inet dhcpIf that's missing or wrong, fix it and bring the interface up manually with ifup eth0 rather than rebooting the whole VM to test a one-line change.
If apk commands hang instead of failing outright, it's usually a mirror that's slow or unreachable rather than actually broken. Re-run setup-alpine just for the mirror step, or edit /etc/apk/repositories directly and swap in a different mirror from mirrors.alpinelinux.org.
If the VM feels sluggish despite the tiny footprint, double check the disk bus is actually VirtIO SCSI and not the default IDE emulation — it's easy to leave the disk tab on its default setting if you clicked through VM creation quickly.
Best Practices
Take a snapshot immediately after the first successful boot, before you install anything else. Alpine installs take under a minute, but re-answering a dozen setup-alpine prompts from scratch gets old fast if you break something later and want to roll back to a clean base.
Install doas instead of reaching for full sudo if you want a non-root user for daily work — apk add doas gets you a lightweight equivalent that's more in keeping with how minimal the rest of Alpine is. Add an entry to /etc/doas.d/doas.conf like permit persist yourusername as root and you're set.
Keep your package additions deliberate. It's tempting to apk add a pile of familiar tools out of habit, but part of the point of Alpine is staying small — if you're installing half of what a full Ubuntu Server ships with by default, you've lost the reason you picked Alpine in the first place.
Frequently Asked Questions
Can I resize the disk after installing?
Yes. Resize it from the Proxmox Disks tab as you would for any VM, then inside Alpine use apk add parted e2fsprogs-extra followed by growpart and resize2fs (or the equivalent for your filesystem) to extend the partition and filesystem into the new space.
Does Alpine support cloud-init like the Ubuntu templates I might already be using?
Not out of the box the way Ubuntu's cloud images do. Alpine publishes a cloud-init package you can add manually, but it's not baked into the ISO install the way it is for Ubuntu's official cloud images, so setting up automated provisioning takes more manual work.
Why did apk add bash fail with an "unsatisfiable constraints" error?
Almost always the community repository line in /etc/apk/repositories is still commented out. Uncomment it, run apk update, and try again.
Is Alpine a good choice for running Docker?
It works, and it's genuinely popular as a base image inside containers. As a Docker host itself it's less common in production because some storage driver combinations behave differently under musl than glibc — worth testing your specific workload before committing to it for anything important.
Should I use a VM or an LXC container for this?
Proxmox ships a built-in Alpine container template, and for a lot of simple use cases an LXC container is genuinely simpler and lighter than a full VM. Reach for a VM instead when you want real kernel isolation, need to test something that behaves differently at the kernel level, or just want the VM to behave exactly like it would on bare metal.
Conclusion
None of the individual steps here are difficult — the whole install takes maybe ten minutes once you know what setup-alpine is going to ask. The friction is almost entirely about unfamiliarity: different init system, different package manager, an installer that's a single command instead of a graphical wizard. Once you've done it once, spinning up a second or third Alpine VM for some small, single-purpose job becomes something you can do without thinking twice about the RAM or disk space it'll cost you.