Docker "image operating system ... cannot be used" (Windows vs Linux) in CI

By Daniel Zoghalchali·Latchkey

The image was built for a different operating system than the daemon. image operating system "windows" cannot be used on this platform means you tried to run a Windows image on a Linux daemon (or the reverse) - the OSes must match.

What this error means

A docker run/docker pull fails with image operating system "windows" cannot be used on this platform (or "linux" cannot be used on a Windows daemon). Switching to an image of the daemon OS works.

docker

docker: image operating system "windows" cannot be used on this platform.
# a Windows base image was pulled on a Linux runner

Common causes

Windows image on a Linux daemon

Windows container images can only run on a Windows daemon. A Linux runner cannot execute them - the OS field of the image does not match the host.

Linux image on a Windows daemon

The reverse also fails unless the Windows daemon is in Linux-container mode; otherwise the image OS does not match.

A FROM that pulls the wrong-OS base

A Dockerfile based on a Windows image built on a Linux runner hits this at pull/build time.

How to fix it

Run on a host matching the image OS

Use a Windows runner for Windows images and a Linux runner for Linux images.

.github/workflows/build.yml

# Windows images require a Windows runner:
jobs:
  build:
    runs-on: windows-latest

Choose a base image for your runner OS

Pick a Linux base on Linux runners (or vice versa).

Dockerfile

# on a Linux runner, use a Linux base:
FROM mcr.microsoft.com/dotnet/aspnet:8.0   # linux variant
# not the windows/nanoserver variant

How to prevent it

Match the runner OS to the image OS (Windows images need Windows runners).
Pick base images for the platform you build on.
Keep Windows and Linux image pipelines on separate runners.

Frequently asked questions

What causes ""image operating system ... cannot be used""?