This error occurs when Docker is configured to run Windows containers but you're trying to use a Linux-based image, or vice versa. The solution is to switch Docker Desktop to the correct container mode or use WSL 2 for running Linux containers on Windows.
This error indicates a mismatch between the container operating system type and Docker's current configuration. Docker Desktop on Windows can run either Windows containers or Linux containers, but not both simultaneously (without additional setup). When you see "image operating system 'linux' cannot be used on this platform," Docker is currently configured for Windows containers but you're trying to pull or run a Linux-based image. The reverse error "image operating system 'windows' cannot be used on this platform" occurs when Docker is set to Linux mode but you're trying to use a Windows container image. Docker containers share the kernel with the host operating system, which is why they need matching OS types. On Windows, Docker Desktop uses either Hyper-V or WSL 2 to run a Linux virtual machine that can host Linux containers, while Windows containers run natively on the Windows kernel.
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: linuxIf 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 installationAfter 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-ComputerImportant: 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 infoIf 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
winverIf 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.
### Running Both Linux and Windows Containers Simultaneously
By default, Docker Desktop only allows one container type at a time. However, you can run both by installing Docker Engine inside WSL 2:
# Inside your WSL 2 distribution (e.g., Ubuntu)
curl -fsSL https://get.docker.com | sh
# Start Docker daemon
sudo service docker start
# Expose Docker on localhost
sudo dockerd -H tcp://127.0.0.1:2375Then create a separate Docker context:
# In Windows PowerShell
docker context create linux-wsl --docker "host=tcp://127.0.0.1:2375"
docker context use linux-wslNow you can run Linux containers via the WSL context while Docker Desktop handles Windows containers.
### Windows Server Container Configuration
On Windows Server, configure the Docker daemon for your needs:
# Install Docker on Windows Server
Install-WindowsFeature -Name Containers
Install-Module DockerMsftProvider -Force
Install-Package Docker -ProviderName DockerMsftProvider -Force
# For Linux containers, install WSL
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
# Configure daemon for LCOW (Linux Containers on Windows)
# Edit: C:\ProgramData\docker\config\daemon.json
{
"experimental": true
}### Using Hyper-V Isolation for Container Compatibility
Windows containers can use process isolation (faster) or Hyper-V isolation (more compatible):
# Run with Hyper-V isolation for better version compatibility
docker run --isolation=hyperv mcr.microsoft.com/windows/servercore:ltsc2022Hyper-V isolation allows running containers with different Windows kernel versions than the host, which is useful when container images require specific Windows versions.
### Troubleshooting Switch Option Not Appearing
If "Switch to Linux/Windows containers" doesn't appear in the Docker menu:
1. Ensure Docker Desktop is fully updated
2. Check that virtualization is enabled in BIOS
3. Verify Hyper-V or WSL 2 is properly installed
4. Try restarting the Docker service:
# Restart Docker service
Restart-Service docker
# Or restart Docker Desktop
& "C:\Program Files\Docker\Docker\DockerCli.exe" -SwitchDaemonSome Docker Desktop versions (like 4.25.0) had bugs where this option was missing - update to the latest version.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub