How to fix image operating system "windows" cannot be used on this platform in Docker

First, verify which container mode Docker is currently using:

Check via Docker Desktop:
1. Look at the Docker icon in the Windows system tray
2. Right-click the Docker whale icon
3. If you see "Switch to Windows containers...", you're in Linux mode
4. If you see "Switch to Linux containers...", you're in Windows mode

Check via command line:

docker version

Look at the "OS/Arch" line under "Server". If it shows linux/amd64, Docker is in Linux container mode. If it shows windows/amd64, you're in Windows container mode.

Check the image architecture:

docker manifest inspect mcr.microsoft.com/windows/nanoserver:ltsc2022

This shows the image's target OS and architecture.

If you need to run Windows containers on Windows:

Using the system tray:
1. Right-click the Docker whale icon in the Windows system tray
2. Click "Switch to Windows containers..."
3. Docker Desktop will restart with Windows container support

Note: You'll see a confirmation dialog. Click "Switch" to confirm.

After switching:
- All running Linux containers will stop
- Docker daemon will restart using Windows container backend
- You can now pull and run Windows container images

Important requirements:
- Windows 10/11 Professional, Enterprise, or Education edition
- Windows Home does NOT support Windows containers
- Hyper-V and Containers Windows features must be enabled

Windows containers require specific Windows features to be enabled:

Enable via PowerShell (run as Administrator):

# Enable Containers feature
Enable-WindowsOptionalFeature -Online -FeatureName Containers -All

# Enable Hyper-V (required for isolation)
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Enable via Windows Features GUI:
1. Press Win + R, type optionalfeatures, press Enter
2. Check "Containers"
3. Check "Hyper-V" and all sub-items
4. Click OK and restart when prompted

Verify features are enabled:

Get-WindowsOptionalFeature -Online -FeatureName Containers
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V

Both should show State: Enabled.

If you're on Linux, macOS, or prefer Linux containers, use Linux-based versions of the images:

For .NET applications:

# Instead of Windows nanoserver:
# FROM mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-ltsc2022

# Use Linux-based image:
FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Or explicitly specify Linux:
FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim

Common Windows images and their Linux alternatives:
| Windows Image | Linux Alternative |
|--------------|-------------------|
| mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-ltsc2022 | mcr.microsoft.com/dotnet/aspnet:8.0 |
| mcr.microsoft.com/windows/servercore:ltsc2022 | Use appropriate Linux base (alpine, debian, ubuntu) |
| mcr.microsoft.com/mssql/server:2022-latest (Linux available) | Same image works on Linux |

Update your Dockerfile or docker-compose.yml to use the Linux-based image tags.

CI/CD environments require specific configuration for Windows containers:

Azure DevOps:
Use a Windows-based agent pool:

pool:
  vmImage: 'windows-latest'

steps:
- script: |
    docker pull mcr.microsoft.com/windows/nanoserver:ltsc2022
  displayName: 'Pull Windows image'

For Azure Container Registry builds:

# Specify Windows platform explicitly
az acr build --registry myregistry --image myimage:v1 --platform windows .

GitHub Actions:
Use Windows runner:

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build Windows container
        run: docker build -t myapp:windows .

Important: GitHub Actions and most CI platforms default to Linux runners. Windows container builds require explicit Windows runner configuration.

After switching to Windows containers, verify everything works:

Check Docker mode:

docker version

The Server OS/Arch should now show windows/amd64.

Test pulling a Windows image:

docker pull mcr.microsoft.com/windows/nanoserver:ltsc2022

Run a simple Windows container:

docker run --rm mcr.microsoft.com/windows/nanoserver:ltsc2022 cmd /c "echo Hello from Windows container"

If the pull still fails:
- Ensure you're on Windows Pro/Enterprise/Education (not Home)
- Verify Hyper-V and Containers features are enabled
- Restart Docker Desktop completely
- Check that the Windows version matches the image tag (e.g., ltsc2022 requires Windows Server 2022 or Windows 11)

Docker Desktop can only run one container type at a time. If you need both:

Option 1: Switch between modes as needed
- Use system tray to switch between Linux and Windows containers
- Not ideal for workflows requiring both simultaneously

Option 2: Use separate Docker hosts
- Run Linux containers on WSL 2 Docker instance
- Run Windows containers on Windows Docker daemon
- Use different Docker contexts:

# List available contexts
docker context ls

# Create Windows container context
docker context create windows-containers --docker host=npipe:////./pipe/dockerDesktopWindowsEngine

# Switch context
docker context use windows-containers

Option 3: Use a multi-platform build approach
Build images for both platforms and push to registry:

docker buildx build --platform linux/amd64,windows/amd64 -t myapp:latest --push .

Note: Multi-platform builds require appropriate base images for each platform.