# windows-imaging-tools builds OpenStack and MAAS images from a Windows ISO

> windows-imaging-tools is an Apache licensed bundle of PowerShell modules that automates Windows image generation for OpenStack and MAAS, covering offline cloud images and online images built through a Hyper-V instance.

**cloudbase/windows-imaging-tools** — Tools to automate the creation of a Windows image for OpenStack, supporting KVM, Hyper-V, ESXi and more.

- Repository: https://github.com/cloudbase/windows-imaging-tools
- Stars: 795 · Forks: 243
- Language: PowerShell
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudbase-windows-imaging-tools

## A scripted build for Windows guests on OpenStack and MAAS

Producing a Windows image that boots cleanly on a cloud hypervisor is a manual, error prone job: install Windows on a virtual machine, run the setup, apply drivers, inject the right unattended answer file, generalise the image and convert it into whatever format the platform expects. windows-imaging-tools automates that sequence. The tools are a bundle of PowerShell modules and scripts, and the repository name is Windows OpenStack Imaging Tools even though the supported targets are broader. The supported target environments for the Windows images are OpenStack with KVM, Hyper-V, VMware and baremetal hypervisor types, and MAAS with KVM, Hyper-V, VMware and baremetal. The audience is cloud operators and platform engineers who need Windows capacity and would rather rebuild the image in a pipeline than maintain it by hand. The generation environment has to be a Windows one with Hyper-V virtualization enabled, unless you intend to run the online setup step elsewhere, in which case Hyper-V is not required. Everything is driven by an ini configuration file, which is what makes the process repeatable.

## A wide span of Windows releases, and where Nano Server is not

The list of guest versions the tools can generate covers both client and server releases. Supported are Windows Server 2008 and 2008 R2, 2012 and 2012 R2, 2016, 2019, 2022 and 2025, plus Windows 7, 8, 8.1, 10 and 11, with both x86 and x64 where such a version exists. That is an unusually broad matrix for an image builder, and it covers the range that MAAS and OpenStack operators actually have to support, from decade old servers to current releases. The important exclusion is stated plainly: to generate Windows Nano Server 2016 you should use a different repository, the cloudbase-init-offline-install project. So this is the general purpose Windows image builder rather than a minimal container style OS builder. The repository also contains an Unattend.xslt and UnattendTemplate.xml, which are the pieces that turn a plain install into an unattended one, and a kms_product_keys.json file that maps product editions to keys.

## Two generation commands with very different output

The core of the tool is two commands, and the choice between them changes what you end up with. New-WindowsCloudImage does not require Hyper-V to be enabled, but the generated image is not ready to be deployed, as it needs to be started manually on another hypervisor; the image is ready to be used when it shuts down. In practice this produces a VHD that carries the install state but has not yet been booted, so someone has to boot it once elsewhere for the install to complete. New-WindowsOnlineImage requires Hyper-V to be enabled, and a VMSwitch configured for external network connectivity if the updates are to be installed, which is highly recommended. It uses New-WindowsCloudImage internally to generate the base image, starts a Hyper-V instance with that base image, and after the instance shuts down the resulting VHDX is shrinked to a minimum size and converted to the required format. That second path is the one that produces a finished artefact, and the online step is also what lets Windows Update run inside the image before it is captured.

## Configuration is an ini file edited through PowerShell helpers

The workflow is a script you can read. The documentation walks through cloning the repository, importing the modules, generating a config file with a built in function and then setting the values you need:

```powershell
git clone https://github.com/cloudbase/windows-openstack-imaging-tools.git
pushd windows-openstack-imaging-tools
Import-Module .\WinImageBuilder.psm1
Import-Module .\Config.psm1
Import-Module .\UnattendResources\ini.psm1
# Create a config.ini file using the built in function, then set them accordingly to your needs
$ConfigFilePath = ".\config.ini"
New-WindowsImageConfig -ConfigFilePath $ConfigFilePath
```

Values are then written into sections and keys of that file, which keeps the build declarative:

```powershell
Set-IniFileValue -Path (Resolve-Path $ConfigFilePath) -Section "DEFAULT" `
                                      -Key "wim_file_path" `
                                      -Value "D:\Sources\install.wim"
```

And the build is a single call with the config path:

```powershell
New-WindowsOnlineImage -ConfigFilePath $ConfigFilePath
```

The repository ships worked examples, including create-windows-cloud-image.ps1, create-windows-online-cloud-image.ps1, a create-digital-ocean-windows-image.ps1 and a windows-image-config-example.ini, so the intended pattern is copy the example, edit the config, run the command.

## Submodules, drivers and the ADK are part of the build

The prerequisites list is short but the dependencies are not. You need a Windows host with Hyper-V virtualization enabled, PowerShell version 4 or later support, the Windows Assessment and Deployment Kit, a Windows installation ISO or DVD, Windows compatible drivers if the target environment requires them, and a Git environment. Two details decide whether a build succeeds. First, if the target environment is MAAS or the image generation is configured to install updates, the windows-curtin-hooks and WindowsUpdates git submodules are required, retrieved with git submodule update --init. Second, drivers are not optional in general: on KVM the image needs VirtIO drivers, and the configuration options virtio_iso_path and virtio_base_path tell the tooling where they are, while baremetal boots need either storage drivers builtin into the Windows installation or a correct drivers_path. The ADK matters because it provides the servicing and deployment tooling the image builder drives, and PowerShell 4 is the floor for the module features the scripts rely on.

## Three failure modes the FAQ actually answers

The troubleshooting section is the most useful part of the documentation, because these are the exact ways a build goes wrong. If image generation never stops, check that the Hyper-V VMSwitch is correctly configured and allows Internet connectivity if you configured the build to install Windows updates, and check that the Logon.ps1 script inside the associated Hyper-V VM has not failed, which shows as a PowerShell window with the error message. If a booted instance gives a blue screen, the fix depends on where it boots: on KVM, configure the correct path for the ISO or folder with VirtIO drivers using virtio_iso_path and virtio_base_path, and start the KVM vm process with the --enable-kvm flag; on baremetal, ensure the basic Windows installation has the storage drivers builtin or point drivers_path at the right folder. If the instance hangs on the Windows loading screen, the cause is usually that the hypervisor does not expose the CPU flags that specific Windows version requires.

## Apache-2.0 licence, no tagged releases, tests with Pester

The maintenance signals are decent but the release hygiene is thin. The licence is Apache-2.0, with the terms in a License file at the repository root, which is a permissive licence that does not force you to open source your own tooling. The repository has no GitHub releases, so there is no tagged version to pin and no changelog of published binaries to compare against, although the tree does hold a WindowsImageBuilder.psd1 and WindowsImageConfig.psd1 module manifest pair. The last push to the repository was on 2026-10-12, and CI runs through AppVeyor on the master branch. For developers, the test suite uses the Pester package, which the documentation says should already be installed on Windows 10, and can be installed with Install-Package Pester. Running the tests in a closed environment uses cmd /c 'powershell.exe -NonInteractive { Invoke-Pester }', which avoids polluting the current shell environment and is not needed in a Continuous Integration environment.

## Conclusion

Adopt windows-imaging-tools if you publish Windows guests to OpenStack or MAAS and want the image build scripted rather than hand installed, and if you can supply a Windows host with Hyper-V enabled plus the ADK. Do not adopt it for Windows Nano Server images, since the project points those builds at a separate repository, or for hosts without Hyper-V if you need a boot ready image, because the offline path produces an image that must be started manually elsewhere. Verify first that the target hypervisor exposes the CPU flags the Windows version requires, that the virtio driver paths are set for KVM, and that the git submodules are initialised before you start a build.

## FAQ

### How do I generate a Windows image for OpenStack with windows-imaging-tools?

Clone the repository, import WinImageBuilder.psm1, Config.psm1 and UnattendResources/ini.psm1, create a config.ini with New-WindowsImageConfig, set the values with Set-IniFileValue and then run New-WindowsOnlineImage or New-WindowsCloudImage with that config file.

### What is the difference between New-WindowsCloudImage and New-WindowsOnlineImage?

New-WindowsCloudImage does not need Hyper-V, but the generated image is not ready to be deployed and must be started manually on another hypervisor, becoming usable once it shuts down. New-WindowsOnlineImage requires Hyper-V with a VMSwitch for external connectivity if updates are installed, and it starts a Hyper-V instance, then shrinks the VHDX and converts it to the required format.

### My booted instance shows a blue screen of death. What should I check?

On KVM, set the correct VirtIO driver paths through the virtio_iso_path and virtio_base_path options and start the KVM vm process with the --enable-kvm flag. On baremetal, make sure the basic Windows installation has the storage drivers builtin or point the drivers_path option at the right folder.

### Can windows-imaging-tools build Windows Nano Server images?

No. The documentation says that to generate Windows Nano Server 2016 you should use the separate cloudbase-init-offline-install repository. This project covers the standard Windows client and server releases.

## Sources

- [cloudbase/windows-imaging-tools on GitHub](https://github.com/cloudbase/windows-imaging-tools)
- [Issues](https://github.com/cloudbase/windows-imaging-tools/issues)
- [License: Apache-2.0](https://github.com/cloudbase/windows-imaging-tools/blob/master/LICENSE)
- [README](https://github.com/cloudbase/windows-imaging-tools/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cloudbase-windows-imaging-tools