Have you ever wondered how docker works seamlessly across different operating systems (OS)? I write a Dockerfile on a Windows laptop. My teammate builds it on a Mac. CI builds and creates image on Linux. It works the same everywhere, even when it contains something like RUN chmod +x blah.sh. Windows has no chmod, so how does this work? How a simple docker buiuld ... command builds the same image across Linux, macOS, and Windows?
How Docker Runs the Same Dockerfile across OSs
The answer is that Dockerfile never runs on the host OS.
A container is a Linux process, not a tiny OS. A container does not bring its own kernel. It is a normal Linux process with a restricted view of the system. Linux gives Docker two kernel features for this:
- Namespaces: give the process its own private view of processes, network, mounts and hostname.
- cgroups: limit how much CPU and memory it can use.
So every Linux container needs a Linux kernel underneath it. Docker makes sure one is always there:
- On Linux: Docker uses the host kernel directly.
- On macOS: Docker Desktop starts a small hidden Linux VM.
- On Windows: Docker Desktop uses WSL2, which runs a real Linux kernel in a lightweight VM.
The docker command on our Mac or Windows machine is only a client. The real work happens in a daemon running inside that Linux environment. When a Dockerfile runs chmod, it is a real Linux syscall on a real Linux filesystem. Nothing is translated to NTFS or APFS.
From Dockerfile to image
An image is built one instruction at a time, and most instructions produce a layer.
- Base image:
FROM ubuntu:24.04pulls the base layers from a registry. These are tarballs of a minimal Linux userland (libc, bash, coreutils and so on). There is no kernel in them, because the container borrows the host or VM kernel. - BuildKit parses the Dockerfile into a graph of steps. Each step has a cache key made from the parent layer, the instruction text and, for COPY, a checksum of the input files.
- COPY takes files from the project, which Docker sends to the daemon as a tarball called the build context. This is the only step where host’s quirks can leak in. Windows has no Unix execute bit, so files arrive without it, and that is why we need the chmod.
- RUN executes in a temporary container. runc creates new namespaces (pid, mount, network and others) and cgroups. It mounts the layers so far with overlayfs and a writable layer on top, then runs for example
/bin/sh -c "chmod +x blah.sh"and stops. Docker then compares the filesystem before and after. The difference becomes a layer. Docker packs the changes into a tar archive, compresses it and hashes it with sha256. The hash is the layer’s identity. Deleted files are recorded with special “whiteout” markers. - ENV, CMD, ENTRYPOINT and WORKDIR don’t create filesystem layers. They only change the image’s metadata.
If nothing changed, Docker reuses the cached layer. That is why putting rarely changing steps first makes builds fast.
What an Image Actually is
An image is three kinds of files, all named by the hash of their content:
- Layer blobs: the compressed tarballs from the steps above.
- Config JSON: environment variables, the default command, the target OS and CPU architecture, and build history.
- Manifest: a small JSON file listing the config and the layers in order.
Registries store and serve these blobs as they are. Because they are named by content, identical layers are shared between images, and a push only uploads what the registry doesn’t have.
What Happens when we Run it
docker run mounts the read-only layers together using overlayfs and adds a thin writable layer on top. runc starts the CMD process inside that merged filesystem with fresh namespaces and cgroups. Nothing is copied and no OS boots, which is why containers start in milliseconds.
One Real Limit: CPU Architecture
Even though Docker smartly hides the OS differences with the Linux VM, but it cannot hide the CPU. The binaries inside the layers are compiled for one architecture, usually amd64 or arm64, and the image records which one.
An Apple Silicon Mac builds arm64 images by default. If we push one to an x86 server, we get exec format error. We need to pass platform flag to build architecture specific image e.g. docker buildx build --platform linux/amd64 . A multi-platform tag points to an index with one manifest per architecture, and each machine pulls the one that matches its CPU.
References
- Docker Desktop WSL 2 backend on Windows
- Virtual Machine Manager (Docker Desktop)
- The Magic Behind the Scenes of Docker Desktop
- OCI Image Format Specification
- OCI Image Configuration (DiffID, layers)
- OCI Image Layer Filesystem Changeset (whiteouts, gzip/zstd)
- Docker build cache invalidation
- Docker multi-platform images (mirror of the docs page)
- Multi-Platform Docker Builds (Docker blog)
- Docker and OverlayFS in practice (older moby docs mirror)