The intersection of Microsoft Windows and the Docker containerization ecosystem represents one of the most complex and misunderstood landscapes in modern infrastructure management. For years, the community has sought a seamless way to run the full Windows desktop experience—specifically Windows 10 and Windows 11—within lightweight containerized environments. However, the reality of Microsoft’s official support structure creates a rigid boundary between server-oriented containerization and desktop virtualization. This dichotomy forces administrators, developers, and enthusiasts to navigate two distinct paths: the officially supported, headless Windows Server containers provided by Microsoft Container Registry, and the community-driven, virtualization-heavy workarounds hosted on Docker Hub that attempt to bridge the gap by running full desktop operating systems inside containers. Understanding the technical nuances, limitations, and configuration requirements of both approaches is essential for anyone attempting to deploy Windows environments in a Dockerized infrastructure. The confusion often stems from a fundamental misunderstanding of what a container is versus what a virtual machine is, and how Microsoft’s licensing and architectural decisions dictate what can and cannot be run in these environments.
Official Microsoft Windows Container Base Images
Microsoft provides official support for running Windows containers, but this support is strictly limited to server operating systems. The official base images are designed to run .NET Framework applications, .NET Core applications, and other services that do not require a graphical user interface. These images are distributed through the Microsoft Container Registry (MCR) and are discoverable via Docker Hub. The MCR is a secure, high-performance repository that leverages Azure’s global content delivery network to ensure fast and consistent image pulls. Azure customers benefit significantly from this integration, as the in-network speeds and tight integration with Azure Marketplace and other Azure services provide a seamless deployment experience for enterprise workloads. The pull commands for these images typically reference the MCR directly, such as docker pull mcr.microsoft.com/windows/servercore:ltsc2025.
The availability of these images is tied to specific Windows Server versions. As of the latest updates, Microsoft supports Windows Server 2025, Windows Server 2022, Windows Server 2019, and Windows Server 2016. Each of these versions offers different container base images that vary in their on-disk footprint and the specific sets of Windows APIs they expose. The choice of base image is critical for optimizing resource usage and ensuring compatibility with the applications being deployed. For most users, the two most appropriate images to target are Windows Server Core and Nano Server. These images represent the core of Microsoft’s container strategy, focusing on minimalism and performance.
Windows Server Core versus Nano Server
The distinction between Windows Server Core and Nano Server is fundamental to understanding how Windows containers operate. Windows Server Core is a reduced installation option for Windows Server that provides a minimal operating system environment. It lacks the traditional GUI (Graphical User Interface) but retains many of the core components needed to run services. In contrast, Nano Server is an even more minimalized version of the operating system. It has a significantly smaller API surface area, which results in a much smaller on-disk footprint. This makes Nano Server ideal for hosting containerized workloads where resource efficiency is paramount.
One of the key technical differences between these two images is the absence of certain components in Nano Server. Specifically, PowerShell, Windows Management Instrumentation (WMI), and the Windows servicing stack are not included in the Nano Server image. This absence reduces the attack surface and the overall size of the container, but it also limits the ability to manage the container using traditional Windows administration tools. Nano Server provides just enough API surface to run applications that depend on .NET Core or other modern open-source frameworks. This tradeoff is intentional, as Microsoft aims to provide a lightweight environment that can scale efficiently in cloud and hybrid environments. Users can always add layers on top of Nano Server as needed, but the base image itself is stripped down to the essentials.
Image Discovery and Registry Integration
The discovery of Windows container base images is facilitated by Docker Hub, even though the images themselves originate from the Microsoft Container Registry. This integration allows users to browse and pull images using familiar Docker commands. The MCR does not have its own catalog experience in the same way that Docker Hub does, but it supports existing catalogs to ensure ease of use. The Azure Content Delivery Network plays a crucial role in this process, delivering images with consistent speed and reliability. For Azure customers, this integration is particularly beneficial, as many Azure services now use containers as their primary deployment format. This alignment between Microsoft’s cloud infrastructure and its container strategy ensures that organizations can leverage the full power of Windows containers in their Azure deployments.
It is important to note that certain images may not be available for all Windows Server versions. For example, the Windows image is not available for Windows Server 2025 in all configurations. This limitation reflects the ongoing development and stabilization process of new operating system versions. Users must carefully check the availability of specific images for their target Windows Server version to ensure compatibility.
The Windows Insider Program and Container Images
Microsoft also provides "insider" versions of each container base image for users who want to test the latest features and developments. These insider container images are designed for use with hosts that are running insider versions of Windows, such as Windows Insider or Windows Server Insider. This allows developers and testers to stay on the cutting edge of container technology and provide feedback to Microsoft on new features and improvements.
The following insider images are available on Docker Hub:
- mcr.microsoft.com/windows/servercore/insider
- mcr.microsoft.com/windows/nanoserver/insider
- mcr.microsoft.com/windows/server/insider:10.0.20344.1
- mcr.microsoft.com/windows/insider
These images include the latest feature development in Microsoft’s container images. Using these images requires a host that is enrolled in the Windows Insider Program, as the insider versions of the container images are designed to work with the insider builds of the operating system. This ensures that the container runtime and the host operating system are aligned in terms of features and stability.
Understanding Version Numbers and Confusion
A common source of confusion for users trying to find Windows 10 or Windows 11 container images is the version numbering scheme used by Microsoft. Many users see references to Windows 10 in the context of Windows Server containers and assume that these images can run the Windows 10 desktop experience. However, this is not the case. The version numbers seen on the Docker Hub pages for Windows Server images refer to the base Windows version used by the server, not the desktop operating system. For example, a user checking their Windows 11 OS version using PowerShell might see an output like 10.0.22631.0. This output indicates that Windows 11 is built on the same core as Windows 10, but it does not mean that a Windows 10 container image will provide a Windows 10 desktop environment.
The official Microsoft Windows container images are strictly for server use. They do not include the graphical user interface, and they are not designed to run desktop applications. This limitation is a direct result of Microsoft’s licensing and architectural decisions. Docker itself does not support GUI in Windows containers, as the container runtime is designed for headless server workloads. Therefore, users looking to run Windows 10 or Windows 11 desktop environments in Docker must look to community-driven solutions rather than official Microsoft images.
Community-Driven Windows Desktop Containers: The Dockur Project
While Microsoft does not provide official support for running Windows 10 or Windows 11 desktop environments in containers, the community has stepped in to fill this gap. One of the most popular solutions is the dockurr/windows image, available on Docker Hub. This project, created by a user named dockurr, allows users to run Windows inside a Docker container. However, it is important to understand that this is not a traditional container in the sense of a lightweight, isolated process. Instead, it is a virtual machine running inside a container, leveraging hardware virtualization to provide a full Windows desktop experience.
The dockurr/windows image has gained significant popularity, with over one million pulls on Docker Hub. This popularity underscores the demand for a way to run Windows desktop environments in a Dockerized infrastructure. The project provides a simple and automated way to install Windows 10 or Windows 11 in a container, making it accessible to users who may not have extensive experience with virtualization or containerization.
Installation and Configuration Steps
The installation process for the dockurr/windows image is designed to be as simple as possible. Users can start the container and connect to port 8006 using a web browser. The installation is fully automatic, and users can sit back and relax while the system performs the necessary setup. Once the desktop is visible, the Windows installation is ready for use. By default, the image installs Windows 11 Pro, but users can specify a different version or configuration if needed.
The following are the basic steps to get started:
- Start the container and connect to port 8006 using your web browser.
- Wait for the automatic installation to complete.
- Once the desktop is visible, the Windows installation is ready for use.
This simplicity is one of the key advantages of the dockurr/windows image. It abstracts away the complexity of virtualization and containerization, providing a user-friendly experience for those who want to run Windows in a Docker environment.
Docker Compose and CLI Configuration
For users who prefer to use Docker Compose or the Docker CLI, the dockurr/windows project provides detailed configuration options. The following is an example of a Docker Compose file that can be used to run the Windows container:
yaml
services:
windows:
image: dockurr/windows
container_name: windows
environment:
VERSION: "11"
devices:
- /dev/kvm
- /dev/net/tun
cap_add:
- NET_ADMIN
ports:
- 8006:8006
- 3389:3389/tcp
- 3389:3389/udp
volumes:
- ./windows:/storage
restart: always
stop_grace_period: 2m
This configuration specifies the image to use, the container name, the version of Windows to install, and the devices and capabilities that the container needs. The devices section includes /dev/kvm and /dev/net/tun, which are required for hardware virtualization and network tunneling, respectively. The cap_add section adds the NET_ADMIN capability, which is needed for network administration tasks. The ports section maps the container’s ports to the host’s ports, allowing users to access the Windows desktop via a web browser (port 8006) and Remote Desktop Protocol (ports 3389). The volumes section maps a local directory to the container’s storage, allowing users to persist data across container restarts.
Alternatively, users can run the container using the Docker CLI. The following command achieves the same result as the Docker Compose file:
bash
docker run -it --rm --name windows -e "VERSION=11" -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN -v "${PWD:-.}/windows:/storage" --stop-timeout 120 docker.io/dockurr/windows
This command specifies the image, the environment variables, the ports, the devices, the capabilities, and the volumes. The --rm flag ensures that the container is removed when it stops, while the --stop-timeout flag specifies the amount of time to wait before forcefully stopping the container.
Kubernetes Deployment
For users who want to deploy the Windows container in a Kubernetes environment, the dockurr/windows project provides a Kubernetes YAML file that can be applied using kubectl. The following command applies the configuration:
bash
kubectl apply -f https://raw.githubusercontent.com/dockur/windows/refs/heads/master/kubernetes.yml
This command allows users to deploy the Windows container in a Kubernetes cluster, leveraging the scalability and management features of Kubernetes. However, it is important to note that running a full Windows desktop environment in Kubernetes can be resource-intensive and may not be suitable for all use cases.
Advanced Networking and Resource Configuration
The dockurr/windows image provides several advanced configuration options that allow users to customize the network and resource settings of the container. One of the most common requirements is to assign an individual IP address to the container. This can be achieved by creating a macvlan network, which allows the container to appear as a separate device on the local network.
Creating a Macvlan Network
To create a macvlan network, users can use the following Docker command:
bash
docker network create -d macvlan \
--subnet=192.168.0.0/24 \
--gateway=192.168.0.1 \
--ip-range=192.168.0.100/28 \
-o parent=eth0 vlan
This command creates a new network with the specified subnet, gateway, and IP range. The parent option specifies the network interface that the macvlan network will be attached to. Users must modify these values to match their local subnet configuration.
Once the network is created, users can update their Docker Compose file to use the new network and assign a specific IP address to the container:
yaml
services:
windows:
container_name: windows
networks:
vlan:
ipv4_address: 192.168.0.100
networks:
vlan:
external: true
This configuration assigns the IP address 192.168.0.100 to the container and specifies that the vlan network is external. An added benefit of this approach is that port mapping is no longer necessary, as all ports will be exposed by default. However, it is important to note that the IP address assigned to the container will not be accessible from the Docker host due to the design of macvlan, which does not permit communication between the container and the host on the same network segment.
Resource Allocation and Customization
By default, the dockurr/windows container is configured to use two CPU cores and 4 GB of RAM. However, users can adjust these settings to match their specific requirements. This is done by setting environment variables in the Docker Compose file:
yaml
environment:
RAM_SIZE: "8G"
CPU_CORES: "4"
This configuration allocates 8 GB of RAM and four CPU cores to the container. Users can increase or decrease these values based on the resources available on their host system and the performance requirements of their workload.
User Credentials and Language Settings
By default, the dockurr/windows image creates a user called Docker with the password admin. However, users can customize these credentials to enhance security or meet specific organizational requirements. This is done by setting the USERNAME and PASSWORD environment variables:
yaml
environment:
USERNAME: "bill"
PASSWORD: "gates"
This configuration creates a user called bill with the password gates. Users should choose strong, unique passwords to ensure the security of their Windows environment.
Additionally, users can specify the language of the Windows installation by setting the LANGUAGE environment variable. The following languages are supported:
- Arabic
- Bulgarian
- Chinese
- Croatian
- Czech
- Danish
- Dutch
- English
- Estonian
- Finnish
- French
- German
- Greek
- Hebrew
- Hungarian
- Italian
For example, to install the French version of Windows, users can set the LANGUAGE variable to French:
yaml
environment:
LANGUAGE: "French"
This flexibility allows users to tailor the Windows environment to their language preferences, making it more accessible and user-friendly.
Storage and File Sharing
One of the key features of the dockurr/windows image is the ability to share files between the host machine and the Windows container. After the installation is complete, a folder called Shared will appear on the Windows desktop. This folder can be used to exchange files with the host machine, providing a convenient way to transfer data between the two environments.
To specify the folder on the host that will be mapped to the Shared folder in the container, users can include a bind mount in their Docker Compose file:
yaml
volumes:
- ./example:/shared
In this configuration, the ./example directory on the host is mapped to the /shared directory in the container. Users can replace ./example with the path to their desired shared folder. This bind mount ensures that any files placed in the host directory are immediately available in the Windows container, and vice versa. This feature is particularly useful for development workflows, where code and assets need to be shared between the host and the container.
Disk Partition Extension
As the Windows container is used, the disk space may become full. In such cases, users can manually extend the disk partition to allocate more space. This is done by accessing the disk management tools in Windows and extending the volume into the unallocated space. The process involves selecting the partition, choosing the extend option, and specifying the amount of additional space to allocate. This manual step is necessary because the container does not automatically expand the disk partition as more space is added to the underlying storage.
The Technical Reality: Virtualization Versus Containerization
It is crucial to understand that the dockurr/windows image is not a true container in the traditional sense. Instead, it is a virtual machine running inside a container. This distinction is important because it affects the performance, resource usage, and compatibility of the solution. Traditional containers share the host kernel and are lightweight, while virtual machines have their own kernel and are more resource-intensive. By using hardware virtualization via /dev/kvm, the dockurr/windows image achieves near-native performance, but it still requires significant resources compared to a true container.
This approach allows users to run full Windows desktop environments, including the graphical user interface, which is not supported by official Microsoft Windows container images. However, it also means that users must have hardware virtualization enabled on their host system and must allocate sufficient resources to ensure smooth performance. For users who do not need a GUI or who are running server-based workloads, the official Microsoft Windows container images remain the preferred choice.
Conclusion
The landscape of running Windows in Docker is characterized by a clear divide between official server support and community-driven desktop solutions. Microsoft’s official Windows container images are designed for server workloads, offering minimal, headless environments that are optimized for performance and resource efficiency. These images are available for Windows Server 2016, 2019, 2022, and 2025, and are distributed through the Microsoft Container Registry. They do not support graphical user interfaces or desktop operating systems like Windows 10 or 11.
For users who require a full Windows desktop experience, the dockurr/windows image provides a compelling alternative. By leveraging hardware virtualization, this community-driven solution allows users to run Windows 10 and 11 in a Docker container, complete with a GUI and file-sharing capabilities. While it is not a true container in the traditional sense, it offers a practical and accessible way to deploy Windows desktop environments in a Dockerized infrastructure. Users must carefully configure networking, resource allocation, and storage to ensure optimal performance and security.
Understanding the technical distinctions and limitations of these approaches is essential for making informed decisions about Windows containerization. Whether deploying server-based workloads on Azure or running desktop applications for development and testing, users have a range of options available to meet their specific needs. The continued evolution of container technology and the growing demand for flexible deployment options ensure that the conversation around Windows in Docker will remain relevant and dynamic in the years to come.