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

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 211 views

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.

Quick fix

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

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

Switch to Linux containers using Docker Desktop GUI
Switch containers using the command line
Enable WSL 2 backend for Linux containers
Enable Hyper-V for Windows containers

docker — error

$# After switching, verify the mode by checking Docker info
docker info | findstr "OSType"
# Should output: OSType: linux
image operating system "linux" cannot be used on this platform

What this error means

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.

Typical symptoms

Docker pull fails with 'image operating system linux cannot be used on this platform'
Docker run immediately fails when trying to start a Linux-based container
Docker Compose fails to start services with OS mismatch errors
CI/CD pipelines fail when running on Windows build agents
The same Docker commands work on macOS or Linux but fail on Windows
Error message includes 'image operating system windows cannot be used on this platform' (reverse scenario)

Common causes

Docker Desktop is set to Windows containers mode when trying to run Linux images (most common)
Docker Desktop is set to Linux containers mode when trying to run Windows images
WSL 2 backend is not enabled or properly configured
Hyper-V is not installed or enabled on Windows
Windows Home edition is being used without WSL 2 (cannot run Windows containers)
Docker context is pointing to the wrong daemon
Recent Docker Desktop update reset container mode settings
Windows Server is configured for wrong container type

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

1Switch to Linux containers using Docker Desktop GUI

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)

bash

# 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.

2Switch containers using the command line

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

powershell

# 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.

3Enable WSL 2 backend for Linux containers

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:

powershell

# 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.

4Enable Hyper-V for Windows containers

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

powershell

# 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.

5Check and fix Docker context configuration

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

powershell

# 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.

6Verify Windows edition and limitations

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:

powershell

# 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.

7Reset Docker Desktop to fix corrupted settings

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:

powershell

# 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.

Advanced notes

### 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:

bash

# 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:2375

Then create a separate Docker context:

powershell

# In Windows PowerShell
docker context create linux-wsl --docker "host=tcp://127.0.0.1:2375"
docker context use linux-wsl

Now 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:

powershell

# 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):

powershell

# Run with Hyper-V isolation for better version compatibility
docker run --isolation=hyperv mcr.microsoft.com/windows/servercore:ltsc2022

Hyper-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:

powershell

# Restart Docker service
Restart-Service docker

# Or restart Docker Desktop
& "C:\Program Files\Docker\Docker\DockerCli.exe" -SwitchDaemon

Some Docker Desktop versions (like 4.25.0) had bugs where this option was missing - update to the latest version.

Frequently asked questions

What does "image operating system "linux" cannot be used on this platform" mean?: 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.
How do I fix "image operating system "linux" cannot be used on this platform"?: 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.
What causes "image operating system "linux" cannot be used on this platform"?: Docker Desktop is set to Windows containers mode when trying to run Linux images (most common) Docker Desktop is set to Linux containers mode when trying to run Windows images WSL 2 backend is not enabled or properly configured
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

📚Docker Official Documentation
📖
Docker Desktop Windows Installation(Official Docs)
📖
Docker Desktop WSL 2 Backend(Official Docs)
📖
Microsoft - Set up Linux containers on Windows(Official Docs)
💬
Stack Overflow - OS mismatch error(Stack Overflow)
💬
Docker Forums - Linux container on Windows error(Stack Overflow)
🐙
GitHub Issue - Switch containers option missing(GitHub)
📝
100 Common Docker Errors & Solutions

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

Quick fix

What this error means

Typical symptoms

Common causes

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

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading