Get started

Up and running in one line

The curl installer works on every supported distro and runs setup for you. Or use your native package manager and run winpodx setup once.

1 · Install

The one-liner installs WinPodX, runs setup, and waits for the first Windows boot (~5–10 min).

Any supported distro

$ curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash

Or via a package manager

openSUSE (Tumbleweed / Leap / Slowroll)

sudo zypper addrepo …home:Kernalix7.repo sudo zypper install winpodx

Fedora 42 / 43 / 44

sudo dnf config-manager addrepo --from-repofile=… sudo dnf install winpodx

Arch / Manjaro

$ yay -S winpodx

NixOS

$ nix run github:kernalix7/winpodx

Debian / Ubuntu (.deb)

$ sudo apt install ./winpodx_<version>_all_debian13.deb

AlmaLinux / Rocky / RHEL (.rpm)

$ sudo dnf install ./winpodx-<version>-0.noarch.el10.rpm

AppImage (any distro)

chmod +x winpodx-*-x86_64.AppImage ./winpodx-*-x86_64.AppImage setup

Uninstall

curl -fsSL …/uninstall.sh | bash -s -- --confirm

After a package / AppImage install, run winpodx setup once to generate the config + compose and confirm host deps — package installs ship the binary only, so they don't kick off a 10-minute Windows download out of the blue. The curl one-liner does this for you.

2 · First-time setup

Already used the curl one-liner? It ran setup — skip to launch.

Auto (host-detected defaults)

$ winpodx setup

Interactive wizard

$ winpodx setup --customize

Setup writes ~/.config/winpodx.toml + compose.yaml, registers the GUI launcher, and confirms FreeRDP + Podman/Docker + KVM. The first app launch then provisions the pod and reaches a usable RDP session in ~5–10 min.

Launch (first run ~5–10 min, then near-instant)

winpodx app run desktop # first launch winpodx pod wait-ready --logs # watch progress

3 · Requirements

Hardware virtualization

An x86_64 or aarch64 CPU with virtualization extensions (VT-x / AMD-V / EL2), and access to /dev/kvm. WinPodX runs Windows in a KVM-backed container — without KVM the install completes but Windows never boots.

Memory & disk

8 GB+ RAM (12 GB+ recommended) and ~30 GB free disk for the Windows image.

Container runtime + FreeRDP

A host container runtime (podman ≥ 4 recommended; docker / libvirt also supported) and FreeRDP 3+. winpodx setup-host fixes kvm-group + /etc/subuid / subgid via one pkexec prompt; winpodx doctor surfaces anything still missing.

Full install docs →