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

DockerBEGINNERMEDIUMUpdated Dec 9, 2025· 246 views

This error occurs when Docker Desktop on Windows is set to run Windows containers, but you're trying to pull or run a Linux-based image. Switching Docker Desktop to Linux containers mode will resolve the issue.

Quick fix

Fixes image operating system "linux" cannot be used on this platform

docker version
  1. Check current container mode
  2. Switch to Linux containers mode via system tray
  3. Enable WSL 2 backend for Linux containers
  4. Toggle container mode to reset state
docker — error
docker version
image operating system "linux" cannot be used on this platform

What this error means

When you see the error "image operating system 'linux' cannot be used on this platform," Docker is telling you there's a mismatch between the container image's target operating system and your Docker daemon's current container mode. Docker Desktop on Windows supports two container modes: - **Linux containers mode** (default): Runs Linux containers using a lightweight Linux VM via WSL 2 or Hyper-V - **Windows containers mode**: Runs native Windows containers directly on the Windows kernel Most Docker images on Docker Hub and other registries are built for Linux. When Docker Desktop is switched to Windows containers mode, it cannot run these Linux images because Windows containers require Windows-based images. This error typically occurs when: - Someone accidentally switched Docker to Windows containers mode - A Windows system update or Docker update changed the mode - Docker Desktop was configured for Windows containers in a specific workflow - You're on a virtualized Windows environment that defaulted to Windows mode

Typical symptoms

  • Error message: "image operating system 'linux' cannot be used on this platform" when pulling images
  • Docker pull fails for common images like nginx, ubuntu, alpine, or node
  • Docker build fails when using Linux-based base images
  • Docker run commands fail with operating system mismatch errors
  • The Docker whale icon in system tray may show a different appearance in Windows mode
  • CI/CD pipelines fail when trying to use standard Docker images

Common causes

  1. Docker Desktop is currently set to Windows containers mode instead of Linux containers mode
  2. Someone manually switched Docker to Windows containers mode via the system tray menu
  3. Docker Desktop was installed with Windows containers mode as the default
  4. A Windows update or Docker Desktop update changed the container mode setting
  5. Running Docker inside a virtualized Windows environment that defaults to Windows mode
  6. Windows Server with Docker Enterprise configured for Windows containers
  7. The Docker context is pointing to a Windows containers daemon

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

1Check current container mode

First, verify which container mode Docker is currently using:

Via System Tray:
1. Look for the Docker whale icon in the Windows system tray (bottom-right)
2. Right-click the Docker icon
3. Look at the menu - it will show either "Switch to Windows containers..." or "Switch to Linux containers..."
4. If you see "Switch to Linux containers...", Docker is currently in Windows mode

Via Command Line:

powershell
docker version

Look at the "OS/Arch" line under the Server section:
- linux/amd64 means Linux containers mode
- windows/amd64 means Windows containers mode

You can also check:

powershell
docker info | findstr "OSType"
2Switch to Linux containers mode via system tray

The quickest way to switch container modes is through the Docker Desktop system tray:

1. Find the Docker whale icon in your Windows system tray (bottom-right corner)
2. Right-click on the Docker icon
3. Click "Switch to Linux containers..."
4. Docker will prompt you to confirm - click "Switch"
5. Wait for Docker to restart (this may take a minute)

After switching, verify the change:

powershell
docker version

The Server "OS/Arch" should now show linux/amd64.

Note: If you don't see the "Switch to Linux containers..." option:
- Docker is already in Linux mode (and the issue might be elsewhere)
- Docker Desktop may need to be restarted
- Check if WSL 2 is properly installed (required for Linux containers on Windows Home)

3Enable WSL 2 backend for Linux containers

If you're on Windows 10/11 Home or want the recommended Docker configuration, ensure WSL 2 is enabled:

Install WSL 2:

powershell
# Enable WSL feature
wsl --install

# Or manually enable required features
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Set WSL 2 as default
wsl --set-default-version 2

Configure Docker Desktop to use WSL 2:
1. Open Docker Desktop
2. Go to Settings (gear icon)
3. Select General
4. Ensure "Use the WSL 2 based engine" is checked
5. Click Apply & Restart

After Docker restarts, it should be in Linux containers mode.

4Toggle container mode to reset state

Sometimes Docker gets stuck in an inconsistent state. Toggling between modes can fix this:

1. Right-click the Docker icon in the system tray
2. Click "Switch to Windows containers..." (even if you want Linux)
3. Wait for Docker to restart
4. Right-click the Docker icon again
5. Click "Switch to Linux containers..."
6. Wait for Docker to restart

This toggle resets Docker's container runtime state and can resolve issues where Docker reports the wrong mode.

Verify the fix:

powershell
docker pull hello-world
docker run hello-world

If this works, Docker is properly configured for Linux containers.

5Verify Windows version and Hyper-V support

Linux containers on Windows require virtualization support:

Check Windows version:

powershell
winver

- Windows 10/11 Home: Requires WSL 2 backend only (no Hyper-V)
- Windows 10/11 Pro/Enterprise: Can use either WSL 2 or Hyper-V backend

Enable Hyper-V (Pro/Enterprise only):

powershell
# Using PowerShell as Administrator
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Or via Windows Features:
1. Press Win + R, type optionalfeatures, press Enter
2. Check Hyper-V and all sub-items
3. Click OK and restart

For Windows Home users:
WSL 2 is your only option for Linux containers. Make sure it's properly installed as described in the previous step.

6Handle Docker in virtualized environments

If you're running Windows in a virtual machine (VMware, VirtualBox, Azure, AWS), nested virtualization must be enabled:

For VMware:
1. Edit the VM settings
2. Go to Processors
3. Enable "Virtualize Intel VT-x/EPT or AMD-V/RVI"

For Hyper-V nested VMs:

powershell
# Run on the Hyper-V host
Set-VMProcessor -VMName <YourVMName> -ExposeVirtualizationExtensions $true

For Cloud VMs (Azure/AWS):
- Azure: Use VM sizes that support nested virtualization (Dv3, Ev3, etc.)
- AWS: Use .metal instance types or Nitro-based instances

If nested virtualization isn't available:
Consider using Docker on a Linux VM directly, or use a remote Docker host.

7Restart Docker Desktop completely

If the issue persists, perform a complete restart of Docker Desktop:

Method 1: Via System Tray
1. Right-click the Docker icon
2. Click "Quit Docker Desktop"
3. Wait 30 seconds
4. Start Docker Desktop from the Start menu

Method 2: Via Task Manager

powershell
# Stop all Docker processes
Stop-Process -Name "Docker Desktop" -Force -ErrorAction SilentlyContinue
Stop-Process -Name "com.docker.backend" -Force -ErrorAction SilentlyContinue
Stop-Process -Name "com.docker.proxy" -Force -ErrorAction SilentlyContinue

# Wait a moment
Start-Sleep -Seconds 5

# Start Docker Desktop
Start-Process "$env:ProgramFiles\Docker\Docker\Docker Desktop.exe"

Method 3: Restart Docker service

powershell
Restart-Service com.docker.service

After restart, verify Linux mode:

powershell
docker info | findstr "OSType"
8Reset Docker Desktop to factory defaults

As a last resort, reset Docker Desktop to its default configuration:

Via Docker Desktop UI:
1. Open Docker Desktop
2. Click the gear icon (Settings)
3. Go to Troubleshoot (or Reset tab)
4. Click "Reset to factory defaults"
5. Confirm the reset

Manual reset (if UI is not accessible):

powershell
# Stop Docker
Stop-Process -Name "Docker Desktop" -Force -ErrorAction SilentlyContinue

# Remove Docker settings (keeps images)
Remove-Item "$env:APPDATA\Docker\settings.json" -ErrorAction SilentlyContinue

# For complete reset, also remove:
Remove-Item -Recurse -Force "$env:APPDATA\Docker" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Docker" -ErrorAction SilentlyContinue

# Restart Docker Desktop
Start-Process "$env:ProgramFiles\Docker\Docker\Docker Desktop.exe"

After reset, Docker should default to Linux containers mode (if WSL 2/Hyper-V is available).

Advanced notes

Understanding Linux vs Windows Containers:

Docker containers share the kernel of their host operating system. This fundamental design means:
- Linux containers require a Linux kernel
- Windows containers require a Windows kernel

On Windows, Docker Desktop provides Linux container support through virtualization:
- WSL 2 backend: Runs a real Linux kernel through Windows Subsystem for Linux
- Hyper-V backend: Runs a lightweight Moby Linux VM

When to use Windows containers:
- Running Windows-specific applications (.NET Framework, Windows services)
- Enterprise environments requiring Windows Server containers
- Applications that depend on Windows APIs

Container mode persistence:
Docker Desktop remembers your last selected container mode. Settings are stored in:
%APPDATA%\Docker\settings.json

You can check the current mode programmatically:

json
// In settings.json, look for:
"linuxContainers": true  // Linux mode
"linuxContainers": false // Windows mode

CI/CD considerations:
Most CI/CD pipelines assume Linux containers. If you're building Docker images locally on Windows and pushing to a CI system, ensure you're in Linux mode to avoid compatibility issues.

Windows Server vs Windows Desktop:
- Windows Server can run Linux containers using Hyper-V isolation (requires Docker EE/Mirantis)
- Windows Desktop uses Docker Desktop which supports both modes out of the box

Frequently asked questions

What does "image operating system "linux" cannot be used on this platform" mean?
When you see the error "image operating system 'linux' cannot be used on this platform," Docker is telling you there's a mismatch between the container image's target operating system and your Docker daemon's current container mode. Docker Desktop on Windows supports two container modes: - Linux containers mode (default): Runs Linux containers using a lightweight Linux VM via WSL 2 or Hyper-V - Windows containers mode: Runs native Windows containers directly on the Windows kernel Most Docker images on Docker Hub and other registries are built for Linux. When Docker Desktop is switched to Windows containers mode, it cannot run these Linux images because Windows containers require Windows-based images.
How do I fix "image operating system "linux" cannot be used on this platform"?
This error occurs when Docker Desktop on Windows is set to run Windows containers, but you're trying to pull or run a Linux-based image. Switching Docker Desktop to Linux containers mode will resolve the issue.
What causes "image operating system "linux" cannot be used on this platform"?
Docker Desktop is currently set to Windows containers mode instead of Linux containers mode Someone manually switched Docker to Windows containers mode via the system tray menu Docker Desktop was installed with Windows containers mode as the default
Is the "image operating system "linux" cannot be used on this platform" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading