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

The quickest fix is to switch Docker Desktop to Linux container mode:

1. Locate the Docker whale icon in your Windows system tray (bottom-right)
2. Right-click on the Docker icon
3. Select "Switch to Linux containers..." from the context menu
4. Wait for Docker to restart (this may take a minute)

# After switching, verify the mode by checking Docker info
docker info | findstr "OSType"
# Should output: OSType: linux

If the menu shows "Switch to Windows containers..." instead, you're already in Linux mode and the issue is elsewhere.

If you prefer the command line or need to script this, use DockerCli.exe:

# Switch between Linux and Windows containers
& "C:\Program Files\Docker\Docker\DockerCli.exe" -SwitchDaemon

# Check current mode
docker version --format '{{.Server.Os}}'

This command toggles between modes. Run it once to switch to Linux containers, or again to switch back to Windows.

Note: This executable is only available with Docker Desktop, not Docker Engine installed separately.

The WSL 2 backend is the recommended way to run Linux containers on Windows. Enable it in Docker Desktop:

1. Open Docker Desktop
2. Click the Settings gear icon
3. Go to General
4. Check "Use the WSL 2 based engine"
5. Click Apply & Restart

If WSL 2 is not installed, set it up first:

# Enable WSL feature (run as Administrator)
wsl --install

# Update WSL to version 2
wsl --set-default-version 2

# Restart your computer after installation

After enabling WSL 2, Docker Desktop can run Linux containers more efficiently.

If you need to run Windows containers, ensure Hyper-V is enabled:

# Run PowerShell as Administrator
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
Enable-WindowsOptionalFeature -Online -FeatureName Containers -All

# Restart your computer
Restart-Computer

Important: Hyper-V is only available on:
- Windows 10/11 Pro, Enterprise, or Education editions
- Windows Server 2016 and later

Windows Home edition users must use WSL 2 and can only run Linux containers.

Docker may be pointing to the wrong daemon. Verify and fix the context:

# List available Docker contexts
docker context ls

# Check which context is active (marked with *)
# NAME         DESCRIPTION      DOCKER ENDPOINT
# default *    Current context  npipe:////./pipe/docker_engine

# Switch to default context if needed
docker context use default

# Verify Docker is working
docker info

If you have multiple contexts configured (e.g., for remote Docker hosts), ensure you're using the local Docker Desktop context.

Your Windows edition determines what container types you can run:

| Windows Edition | Linux Containers | Windows Containers |
|-----------------|------------------|-------------------|
| Windows 10/11 Home | Yes (WSL 2 only) | No |
| Windows 10/11 Pro/Enterprise | Yes | Yes |
| Windows Server 2016+ | Yes (with config) | Yes |

Check your Windows edition:

# Get Windows edition
(Get-ComputerInfo).OsName
# or
winver

If you're on Windows Home, you can only run Linux containers using WSL 2. For Windows containers, you'll need to upgrade to Pro or use Windows Server.

If Docker Desktop settings are corrupted, a reset may help:

1. Open Docker Desktop
2. Go to Settings > Troubleshoot
3. Click "Reset to factory defaults"

Alternatively, reset via command line:

# Stop Docker Desktop
Stop-Process -Name "Docker Desktop" -Force

# Remove Docker Desktop settings (backup first if needed)
Remove-Item -Recurse -Force "$env:APPDATA\Docker Desktop"

# Restart Docker Desktop
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

After reset, you'll need to reconfigure your settings and re-login to registries.