Skip to content

Windows guests

Updated

Virtainer Free runs Windows Server 2019, 2022 and 2025 as VMs, from Free 1.2. Windows desktop and Windows 10/11 IoT Enterprise editions are not supported. The host tells that an image is Windows by reading the image, not by asking you, and then it adjusts the create form, first boot, console and shutdown to match.

The whole path is on the host: you bring a Windows Server installation ISO, Build Windows image installs and prepares Windows unattended and publishes the result as an ordinary image, and you create VMs from it.

Supported in Free 1.2 and later
Windows versions Windows Server 2019, 2022 and 2025 (Server Core and Desktop Experience)
Refused at import Windows Server 2016, Windows 10/11 desktop editions, Windows 10/11 IoT Enterprise
Firmware UEFI only; no Secure Boot, no TPM
Disk and network Drivers are included when you use Build Windows image; imported images must meet the image requirements
Console Shell (SYSTEM) (PowerShell, VGA 0.4.0 or newer) and Rescue console (serial, SAC); RDP, SSH and WinRM if you enable them when building the image.
Snapshots Crash-consistent only (not quiesced)
CPU At most 2 CPU sockets

Not in this release: quiesced (VSS) snapshots.

After a blue screen, Windows restarts itself: images built by Virtainer enable automatic restart and automatic memory dumps. A single recovery after the VM was healthy is not treated as a crash loop; repeated crashes still trigger protection. With guest agent 0.4.1 or newer, Virtainer reads the previous boot’s blue-screen report and shows Crashed and recovered, the crash time, stop code and name, and the memory-dump path when available. The host logs a warning once for each crash. Reinstalling the VM clears the old crash and recovery records.

Open a running Windows VM’s Desktop tab to use its desktop in the browser over RDP through the host, with no RDP client to install. RDP must be enabled in Windows. Sign in with the VM’s Windows credentials; the host does not store them and you enter the password for each connection. The host connects only to that VM’s own trusted address on port 3389.

That address must be a static IPv4 entered in the VM’s network settings or a DHCP lease observed by the host, and the host must have an address on that network. An address reported only by the guest is not enough. The tab explains a missing requirement and offers Check again.

The first RDP certificate the VM presents is remembered by its SHA-256 fingerprint. If it changes, compare the new fingerprint with the VM’s certificate, then explicitly choose Trust the new certificate before connecting. Each VM allows at most two desktop sessions, and sessions are recorded in Settings → Diagnostics → Change audit.

A session ended by Windows, including a connection reset, is recorded as a guest closure. A connection failure includes the underlying reason in the audit and log.

The host serves the Web UI over plain HTTP, so the page warns that the connection between your browser and the host is not encrypted; use the Desktop tab on a trusted network. Clipboard sharing with the guest works only when the page is served over HTTPS, in Chrome or Edge.

Use an HTTPS reverse proxy when the browser-to-host network is untrusted. Signing in as the same Windows user from another browser takes over that user’s session. Switch input methods inside Windows (Win+Space) for Chinese or other composed text; your computer’s input method does not pass through. The desktop stream is uncompressed, so a busy screen can use around 30 Mbit/s.

Open Images and choose Build Windows image. A three-step dialog takes you from an ISO to a ready image. The build then runs unattended on the host, and you follow it on the Operations page.

  • A Windows Server ISO for Windows Server 2019, 2022 or 2025, 64-bit (amd64). Any ISO that contains one of these editions will do, including Microsoft’s evaluation ISOs. ISOs of other products or architectures are refused in step 1 with the reason.
  • Disk space for the image’s disk (40 GiB by default) plus about 1 GiB for the build’s answer disk and 1 GiB of headroom, in addition to the ISO itself (ISOs are limited to 16 GiB).
  • Memory: the build VM takes 4 GiB and 2 vCPUs. The host needs 5 GiB of memory available when you start; otherwise the build is refused and tells you to stop a VM and try again.
  • One build at a time per host. Starting a second one is refused until the first finishes or is cancelled.
  • Internet access on the host only if you choose Install OpenSSH Server (Server 2019 and 2022 download it; see the option below). Nothing else in the build needs the network.

The first step is titled Installation ISO. ISOs on this host lists the ISOs the host already holds, with their size and the number of editions on each. Select one, or add one under Add an ISO:

  • Upload: choose an ISO file. The upload starts as soon as you pick the file; there is no separate upload button. The dialog shows progress, transferred bytes and speed, and Stop upload aborts it. After the last byte the dialog reads the editions on the ISO and selects the new ISO for you. If the upload fails, Retry upload sends the same file again. Uploading an ISO the host already holds selects the existing one instead of storing a duplicate.
  • Download URL: paste an ISO URL (for example the link to a Microsoft evaluation ISO) and press Download ISO. The host downloads it, so you can close the dialog meanwhile; reopen Build Windows image to see the progress. When the download finishes, the ISO it produced is selected. A failed download stays in the list for an hour with the reason.

The host reads the ISO’s edition list without unpacking it. An ISO that isn’t a Windows Server 2019, 2022 or 2025 amd64 ISO is greyed out with the reason: Not supported: only Windows Server 2019, 2022 and 2025 can be built. (or the specific reason it was refused). ISOs you have added stay on the host, so a second build, or a retry, doesn’t need another upload. The bin icon next to an ISO deletes it (Delete ISO); images already built from it are kept, and an ISO that a running build uses can’t be deleted.

Next stays disabled until an ISO on the host is selected, and the reason is shown beside it: Upload in progress… Finish or stop the upload to continue., Download in progress… the ISO is selected when it arrives., This ISO cannot be built from; choose another., Select an ISO to continue. or Upload or download an ISO first. Having chosen a file in the browser is not enough; the ISO has to be on the host.

Press Next.

The second step is titled Edition and options.

Field What it does
Edition The Windows editions found on the ISO, for example Windows Server 2022 Datacenter (Desktop Experience), with Server or Server Core and the build number. Server Core editions have no desktop. Editions that can’t be built are greyed out.
Image name The name the image gets in Images. Suggested from the edition (such as windows-server-2022-datacenter) and changeable. It follows the same rule as an uploaded image: start with a letter or digit, then letters, digits, dots, underscores and hyphens, up to 100 characters. If an image with that name exists, the build is refused.
Disk size (GiB) The size of the image’s disk, 32 to 256, default 40. It is also the smallest disk a VM made from the image can have.
Locale The language, region and keyboard Windows is installed with. Choosing an edition sets it to the ISO’s own language when the dialog offers it, so a Chinese (Simplified) ISO builds a Chinese (Simplified) image; change it if you want something else. The dialog offers a short list (for example English UK, German, French, Japanese, Chinese Simplified/Traditional); the host accepts more through the API.
Enable Remote Desktop Instances from this image accept RDP on port 3389.
Install OpenSSH Server Needed if you want to use the SSH keys you give when creating a VM. Port 22. Downloaded from Windows Update during the build on Server 2019 and 2022, so it needs outbound internet access from the host.
WinRM (PowerShell remoting) From Free 1.3: choose Off (default), HTTP (port 5985), HTTPS (port 5986) or HTTP and HTTPS. HTTP is for internal networks; HTTPS lets your client check the instance certificate. See Connect over WinRM.
Allow simple passwords Turns off the Windows password complexity rule in the image and lets administrator passwords be as short as one character. Recommended only on internal networks: RDP with simple passwords is brute-forced quickly on the internet. See Administrator password rule.

All options are off by default. For every service you turn on (RDP, SSH, WinRM) the build makes sure an inbound allow rule for its port exists, is enabled, applies to all network profiles, Public included, and accepts any source address, and then reads the rules back. If a rule isn’t in place, the build fails instead of producing an image whose service is running but blocked. Without the WinRM option, the build disables the firewall rules Windows ships for WinRM, so WinRM is not reachable from the network.

Press Next. A missing edition or an invalid name or size stops you here with the reason.

The third step, Confirm, summarises the ISO, edition, image name, disk size, locale and your Remote Desktop, OpenSSH, WinRM and simple-password choices, and states what the build holds while it runs: the disk size you chose and 4 GiB of memory. Back returns to change anything; Start build begins.

If the host refuses to start the build, the dialog stays on the summary and shows why. The usual reasons are not enough free disk or memory, another build already running, or an image with that name that already exists.

Start build takes you to the Operations page, showing the build as Build Windows image. Open its row for the details. A Build panel lists the stages with a percentage on the current one, next to a screen capture of the build VM:

Stage What happens
Prepare media The host builds a small answer disk with the unattended setup files, the drivers and the Virtainer Guest Agent.
Install Windows Windows Setup runs unattended in a build VM. This is the longest stage; the percentage follows how much of the disk Setup has written.
Wait for VGA Windows is installed; the host waits for the guest agent inside the build VM to answer.
Prepare Windows The host installs the remaining drivers and guest agent, sets up the Rescue console (EMS), turns off hibernation and Fast Startup, and applies your Remote Desktop, OpenSSH, WinRM and password-policy choices, and opens their firewall rules. Windows may reboot several times.
Seal with sysprep Windows is generalized with sysprep and shuts down.
Convert disk The raw disk becomes a compact qcow2 image.
Verify image The host reads the finished image and requires it to have no warnings: agent, drivers, Rescue console, sysprep state and shutdown state must all check out.
Publish image The image is added to Images.

If Windows requests a restart during preparation or just before sealing, the build restarts it, repeats the checks with your original options and continues automatically. After three such restarts, the build fails with the reason Windows still needs one.

The screen capture is the build VM’s display, refreshed every 10 seconds. It is the quickest way to see what Windows Setup is doing; “No screen captured yet” shows until the VM has started.

How long it takes. On physical hosts, builds finish in about 8 to 23 minutes: Server Core editions take about 7 to 13 minutes, Server 2022 Desktop Experience about 17, and Server 2025 Desktop Experience 18 to 23 (its Setup and first agent start are the slowest). Uploading the ISO is separate and depends on your network: a 7.8 GB ISO took about 15 minutes over a 15 MB/s LAN. The percentage during Install Windows is capped below 60% and the build waits for the guest agent only after Setup has restarted into Windows, so a long Setup is normal, not a hang. Setup is allowed up to 120 minutes and the agent 45 minutes after Setup’s restart. The operation’s log tail is shown with the other operation details.

You can leave the page; the build continues on the host. Closing the browser doesn’t affect it.

Press Cancel on the build’s row on the Operations page at any stage before publishing. The host stops the build VM and deletes everything it staged (the disk, the answer disk, screen captures) and releases the reserved space. The ISO stays. Once the image is being published, the build can’t be cancelled.

If the host’s agent restarts during a build, the build is marked failed with the reason agent restarted during the build and its leftovers are cleaned up. Retry it.

A failed build shows an error in plain English on its operation, the stage it stopped in (marked Failed here in the timeline) and the last screen of the build VM. If the build stopped while preparing media, there is no screen; the page says so. The last screen and the diagnostics are kept until the next build starts, at most 7 days. Staging is cleaned up either way. Two actions appear:

  • Download diagnostics saves windows-build-<id>-diagnostics.tar.gz: Windows Setup’s setupact.log and setuperr.log, sysprep’s setuperr.log, the preparation script’s log and status file, the host’s build logs, and the last screen. The host keeps the bundle for 7 days or until the next build.
  • Retry starts a new build with exactly the same ISO, edition and options. The ISO is already on the host, so nothing is uploaded again.

The common failures:

Reason shown What to do
Windows Setup made no progress for 60 minutes Look at the screen capture: Setup may be waiting on a message. Try again, and if it repeats, check the ISO’s checksum or try another edition. Send the diagnostics if you contact support.
A failure while preparing media, with the path and step in the message The reason names the step and the file or directory involved (for example a full or unwritable storage pool). Fix that and retry.
the guest agent did not answer within 45 minutes after Windows Setup Windows installed but the agent never started. The screen capture shows where Windows is stuck.
the build VM stopped during Windows Setup The build VM exited. Check the last screen and download the diagnostics bundle before retrying.
Windows did not shut down within 10 minutes after sysprep was started Sysprep failed or hung. The diagnostics hold sysprep’s setuperr.log.
the built image is not ready: … The finished image failed verification, for example because EMS or the agent is missing. The reason lists every warning; the build is not published.
the host has N GiB of memory available; a Windows image build needs 5.0 GiB … Start refused. Stop a VM and try again.
another Windows image build is running on this host Start refused. Wait for it to finish or cancel it.
image ‘…’ already exists Pick another Image name, or delete the existing image first.

When the build finishes, the image appears in Images like any other, with its Windows product name and build (for example Windows Server 2022 Datacenter · Build 20348) and no warnings. It records where it came from: the ISO’s checksum, the edition, your options (RDP, SSH, WinRM, simple passwords) and the component versions. The Images page and the create form show what the image was built with. Create a VM from it as described next. Nothing needs to be installed or changed first.

The image contains no accounts of its own and no network setup: it is generalized, so each VM you create from it sets its own hostname, administrator account and password on first boot. The Administrator password used during the build is random, never shown and discarded with the build’s staging.

Pick a Windows image in Create VM (see Create a VM). The form switches to Windows: Linux-only settings disappear (root, sudo, SSH policy, extra users, first-boot package update, cloud-config), and any you send through the API are refused.

  • Administrator account: defaults to Administrator. You can choose another local account name of up to 20 bytes. Reserved names and characters Windows forbids aren’t allowed.
  • Disable the built-in Administrator account: shown only when the administrator name isn’t Administrator, and off by default. We recommend turning it on. Until first boot, the built-in Administrator keeps the random password sealed into the image, which anyone holding the image file can read. With this option, the agent disables that account during first boot. Your named administrator is in the local Administrators group and elevates with Run as administrator. If you leave it off, treat the image file as a secret.
  • Password: required, 1–256 characters, and it must satisfy the rule below. SSH keys alone aren’t enough. Templates don’t store the password, so you enter it for each VM. After creation, the password is never shown again, in the UI or the API: the instance only shows whether a password is set.
  • SSH keys: written to the administrators’ authorized_keys, which takes effect if OpenSSH is installed in the image.
  • Hostname: at most 15 characters, using letters, digits and hyphens only. It can’t be all digits and can’t start or end with a hyphen. Batch-created names must follow the same rule. If you leave it blank, the default computer name is vm- followed by six hexadecimal characters, matching the name generated in the Web UI. Existing VMs keep their names.
  • PowerShell script (optional): runs once as SYSTEM during provisioning. A failing script doesn’t stop provisioning. Its errors show up in the provisioning report.
  • Network: each interface uses DHCP (matched by MAC address) or a static IPv4 address, gateway and up to 16 DNS servers. Static IPv6 isn’t supported yet.

Windows refuses a password that breaks its local policy, and a VM would then run with no account you can sign in to. So the host checks the password when you create or reinstall the VM, and the form shows the rule before you submit. A password that fails is refused with a 400 and the reason. By default an image enforces Windows’ standard rule:

  • at least 8 characters;
  • characters from at least 3 of these 5 classes: uppercase letters, lowercase letters, digits, symbols, and letters without case, such as Chinese or Hebrew (so a password with Chinese characters, a digit and a symbol qualifies);
  • not containing the account name (three or more characters, case-insensitive).

An image built with Allow simple passwords records that, and VMs from it only need a non-empty password; 1234 is accepted. A blank password is still refused. Images you imported rather than built on the host have no such record and follow the standard rule.

Windows reboots once during first boot, and this is expected:

  1. The VM boots, and Windows applies the hostname in the sysprep specialize pass, then reboots.
  2. After the reboot the agent service starts. It applies the network, then the account, password, SSH keys and your script.
  3. The agent reports that provisioning is done for this VM’s current settings. The settings disk is then detached.

The agent doesn’t answer until after the specialize reboot. First boot can take several minutes, depending on the image and VM resources. Until the service starts, the host has no agent signal, and that’s normal. The host doesn’t use ping for this (Windows Firewall blocks it by default). The VM is ready when provisioning reports done, not when it answers ping.

While you wait, the instance’s Provisioning tab (it replaces the Cloud-Init tab for Windows) shows these states:

  • Waiting for the first agent report: the agent hasn’t answered yet.
  • pending → applying → done: the agent’s progress for this VM.
  • Provisioning errors: anything the agent reported, including script errors.

To follow the boot, open the instance’s Rescue console tab. It shows the serial line (SAC).

The instance’s Provisioning tab holds the agent’s report for this VM: the status (pending, applying, done or failed), when the report was received, the guest agent version, whether the hostname, user and password were set, and each error the agent reported, with common causes such as a rejected password explained in plain words. When provisioning fails, a banner at the top of the VM page says so and points to the tab, and the Diagnostics finding quotes the first error.

Typical first-boot times on physical hosts, from VM start: the IP appears after about 25 to 65 seconds, and provisioning reports done after about 80 to 150 seconds (up to about 215 seconds for a Server 2025 Desktop Experience image). No manual reboot is needed. Server 2019 may restart once more on its own after Windows setup finishes to apply the hostname.

For DHCP, the VM’s IP appears in the Instances list and network details after the guest agent reports the address. The first Windows DHCP lease typically arrives roughly one or two minutes after boot, and displaying it can take longer while first-boot setup and address reporting finish. This is an estimate, not a boot deadline. An empty IP field during that time does not mean Windows has failed to boot.

You can choose a static IPv4 address, gateway and DNS servers when creating the VM instead of waiting for a DHCP lease. The configured address can appear immediately, but it is only confirmed inside Windows once the agent reports it; the displayed configuration alone does not prove that the network is ready. Static IPv6 is not supported.

If you need to check the address directly, open the Rescue console and run ipconfig.

Open the instance’s Shell tab for Shell (SYSTEM): PowerShell running as SYSTEM through the guest agent. It needs no guest networking, so you can use it before the VM has an IP address. The console button in the VM list also opens Shell (SYSTEM).

The Shell requires Virtainer Guest Agent (VGA) 0.4.0 or newer. Existing Windows VMs get the new agent on their next boot after the host upgrade. With an older agent, the tab explains the requirement and links to Rescue console, which remains available in the instance’s tabs.

Other ways to connect:

  • Rescue console (always in the instance’s tabs, greyed out while the VM is stopped): a serial connection to Windows’ Special Administration Console (SAC), for checking boot progress and troubleshooting when the network, RDP or SSH is unavailable. EMS/SAC must be enabled in the image. It provides text access, not a graphical desktop. At the SAC> prompt, type cmd, then ch -si 1, and sign in with the VM’s administrator name and password.
  • RDP (3389), if you enabled Remote Desktop when building the image, for a desktop session.
  • SSH (22), if you enabled OpenSSH when building the image, with the keys you gave at creation or the administrator password.
  • WinRM (5985, and/or 5986 from Free 1.3), if you enabled it when building the image, for PowerShell remoting. See Connect over WinRM.

Choose More → Download .rdp file in the Windows VM’s action bar, then open the downloaded file with your local Remote Desktop client (mstsc, Windows App or Remmina). The file contains the VM’s IPv4 address on port 3389 and its administrator username. It contains no password; the client asks for it when you connect. The filename uses the VM’s hostname, or vm-<short id>.rdp for a VM with no custom hostname, without repeating the vm- prefix.

A confirmation appears after the download. For a running VM, it offers Open Desktop tab to connect to that VM in the browser. Otherwise, it tells you to Boot, Resume, or Reset to stopped and then Boot, depending on the VM’s state.

The menu item stays disabled until the VM’s IPv4 address is known, with the reason shown in its text. Your computer must be able to reach that address, usually on the same LAN, and Remote Desktop must be enabled in Windows. If it wasn’t enabled when building the image, the menu item says so; you can still use the download if you enabled RDP inside the VM later.

Sign in with the administrator name and password you gave when creating the VM, using Negotiate authentication. Basic authentication and unencrypted traffic stay off. Free 1.2.0 supports HTTP on 5985; from Free 1.3, you can also build images with HTTPS on 5986. Each instance creates its own certificate, and its page shows the fingerprint to verify. Follow the client commands and certificate checks in Connect to Windows instances over WinRM.

On a provisioned Windows VM:

  • Stopped VM: changing addresses, interfaces or the network is refused. The agent applies network settings only once, during first boot. A normal boot doesn’t rerun specialize, so a new setting would never be applied.
  • Running VM: you can add, detach and reattach DHCP interfaces once first boot has finished. Adding or reattaching a static interface is refused. Security policies stay editable at any time.

To start over with different network settings, reinstall the VM.

Images built by Virtainer from Free 1.3 bring every attached data volume online automatically, whether it was attached at create time or while the VM runs. Images built with Free 1.2, and imported images that keep Windows Server’s default policy, leave new disks offline until you bring them online in Disk Management. To change that once in such a guest, run in PowerShell as administrator:

Terminal window
Set-StorageSetting -NewDiskPolicy OnlineAll

A volume keeps its place on the VM when another is detached, so Windows sees the same disk afterwards. To detach a volume from a running Windows VM, first remove any drive letter or mount on it, or take the disk offline in Disk Management; while Windows still holds the disk, the detach is refused and the volume stays attached.

Reinstall works for Windows VMs too, and it reruns first boot on the new root disk.

  • Same family (Windows → Windows): the administrator account and settings carry over. When a password is set, the form defaults to Keep current password; choose Set a new password to replace it. The stored password is reused on the host without being shown to you. The Disable the built-in Administrator account choice carries over too, and you can change it.
  • Switching Windows ↔ Linux: you must supply the target system’s account and password. The dialog asks for them. For an image that isn’t downloaded yet, choose whether it’s Linux or Windows. The host checks the downloaded image before it replaces the root disk. If the settings don’t fit, the old disk is left untouched.

Before reinstalling a Linux VM as Windows, set any nonzero Memory reclaim target to 0; otherwise the reinstall is refused.

Stop first asks the guest agent to shut Windows down. If the agent can’t, Virtainer falls back to the ACPI power button. A VM that doesn’t stop within 300 seconds is powered off. When the host itself shuts down, it gives each Windows VM up to 120 seconds.

  • Free builds Windows Server 2019, 2022 and 2025 images from an ISO you provide. Other Windows editions and versions can’t be built or imported.
  • Only one image build can run at a time per host, and it needs 4 GiB of memory and 2 vCPUs for its duration.
  • The Windows Shell requires VGA 0.4.0 or newer. Use Rescue console when the agent is unavailable. More → Download .rdp file needs a reachable guest address.
  • Secure Boot, TPM and static IPv6 are not supported. Snapshots are crash-consistent; they do not use VSS to quiesce Windows applications.
  • Memory reclaim is unavailable for Windows. The Hardware panel explains the limitation, and nonzero reclaim targets are refused. If an existing Windows VM has a nonzero target, set it to 0 before reinstalling. CPU and memory resizing have separate requirements; see the Hardware panel for the actions available to that VM.
  • Network settings are applied during first boot. After provisioning, stopped network edits and running static-interface additions are refused; see Changing the network.
  • WinRM HTTPS requires Free 1.3 and an image built with HTTPS enabled; Free 1.2.0 supports HTTP on 5985 only.
  • Images built from media in languages whose built-in administrator account isn’t named Administrator (for example French, Spanish or Russian) are untested; English and Chinese (Simplified) were verified.

For a build that fails, see When a build fails. For a VM created from a built image:

What you see Where to look
Import refused: is a Windows desktop or IoT edition Windows 10/11 or IoT Enterprise. Build the image from Windows Server 2019, 2022 or 2025.
Import refused: Windows Server 2016 (build 14393) is not supported Build the image from Windows Server 2019, 2022 or 2025.
SSH, RDP or WinRM port unreachable Check the image’s recorded options in Images: a service you didn’t enable at build time isn’t reachable. A WinRM port is only reachable when you chose it at build time (HTTPS requires Free 1.3).
Rescue console shows UEFI output but never SAC> EMS is off in the image. Images built on the host have it on; check an imported image for the warning.
Waiting for the first agent report well past a minute Rescue console: has Windows finished specialize and rebooted? Check the image warnings for missing guest-agent components or drivers.
Create refused: does not meet Windows password complexity Use at least 8 characters from at least 3 of the 5 classes and leave out the account name, or build the image with Allow simple passwords.
Provisioning failed The Provisioning tab lists the agent’s errors. Fix the image or settings, then reinstall.
provisioning identity not available The agent couldn’t read the settings disk. The errors explain why.
Waiting for a report for this seed The agent’s last report belongs to an earlier provisioning run, not the current one. It clears once the agent reports for the current settings. If it stays, check Diagnostics.
done but with errors Check the Provisioning tab. A PowerShell script or another non-blocking provisioning step may have reported an error.
No IP shown after first boot Click Refresh guest data in the network details. Check ipconfig through the Rescue console if the address is still missing. Check the image for warnings in Images.
169.254.x.x address with no gateway Windows has not obtained a usable DHCP lease. Allow time for the first lease, then check the DHCP service and network through the Rescue console. You can also use a static IPv4 address at creation.

If provisioning fails or hasn’t finished after 30 minutes, the Diagnostics page shows a Windows provisioning warning for the VM. The VM keeps running so you can inspect it from the Rescue console.

For an import refusal or a warning on an image you prepared yourself, see Importing the image.

Use Build Windows image for the supported unattended workflow. It supplies the drivers and guest agent, applies the options you selected, and verifies the image before adding it to Images. You do not need a separate build machine or a manual installation recipe.

You can also import an image prepared outside Virtainer, for example to include organization-specific software or policies. Its preparation and licensing remain your responsibility. Check the requirements below before importing it; an image that boots on another platform may need different drivers here.

Requirement What to check
Windows Server 2019, 2022 or 2025, amd64 Desktop and IoT editions and Server 2016 are not supported
UEFI installation The disk uses GPT and has an EFI system partition; BIOS-only images are refused
Boot and network drivers Install compatible VirtIO drivers. The boot disk needs viostor as a boot-start service with viostor.sys present; networking needs NetKVM
Guest-agent communication driver Install viosock.inf with the VirtioSocket service so the host can reach the agent
Virtainer Guest Agent v0.3.2 or later Install the Windows service and its sysprep specialize hook before sealing the image
Generalized installation Run sysprep with /generalize /oobe so each VM receives its own identity and first-boot settings
Rescue console Enable EMS/SAC on COM1 at 115200 baud
Clean shutdown Disable hibernation and Fast Startup, then shut the image down cleanly

Use the driver set supplied with the Virtainer Windows image workflow; changing driver providers can make the image fail verification. Secure Boot and TPM remain unsupported. Virtainer does not supply Windows licenses or third-party subscription entitlements.

Leave networking on DHCP and let Virtainer apply the hostname, administrator account and network settings for each VM. The guest-agent service must already be installed: the first-boot settings disk cannot install a missing Windows service. After sealing, do not boot the template again; its next boot must belong to the new VM. To customize it later, work from a copy and seal that copy.

Add the image the same way as a Linux one (see Images) with Add Image, which repeats the driver requirements. Virtainer then reads the image offline. A Windows image shows its product name and build, for example Windows Server 2022 Datacenter · Build 20348. In the image picker it’s labelled Cached once it’s on the host.

Virtainer refuses an image at import if it isn’t a supported version or certainly can’t boot here:

  • It’s Windows 10/11 (desktop or IoT Enterprise) or Windows Server 2016. Only Windows Server 2019, 2022 and 2025 are accepted.
  • The architecture isn’t amd64, or can’t be verified as amd64.
  • The image has no viostor service, viostor isn’t boot-start, or viostor.sys is missing.
  • The image boots only with BIOS.

An image of this kind that’s already on the host is refused the same way when you create or reinstall a VM from it.

Anything else is a warning on the image. You can still use the image, but you should fix the cause:

Warning What it means
Virtainer Guest Agent is missing or unverified Provisioning won’t finish without the agent. Install the Windows build of v0.3.2 or later and its specialize hook.
Windows netkvm / viosock driver is missing or unverified Required networking or guest-agent drivers are missing. Use a compatible prepared image.
Windows edition could not be verified Virtainer couldn’t read the version. Make sure it’s Windows Server 2019, 2022 or 2025.
Not confirmed generalized by sysprep First boot may skip setup, so your hostname and account may not apply.
EMS is disabled or unverified The Rescue console may stay blank.
Fast Startup / hibernation is enabled Shutdowns may not be clean. Turn both off.
Registry hive or NTFS volume is dirty The image wasn’t shut down cleanly, so the facts above may be unreliable. Seal again from a clean copy.