Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 111 ยท Getting Started

Docker Desktop, WSL2 and Colima

Choose and tune a local Docker setup on Windows, macOS and Linux: Docker Desktop, WSL2, Colima and alternatives, resource limits and file-sharing speed.

Docker containers are a Linux feature. On a Linux machine the Docker Engine talks straight to the kernel. On Windows and macOS there is no Linux kernel to talk to, so every local Docker setup quietly adds a hidden Linux virtual machine and runs the engine inside it. Knowing that one fact helps you choose a setup, give it the right amount of memory, and avoid the biggest beginner trap: a project that works but is ten times slower than it should be, only because of where its files live.

This lesson maps out the common local setups: Docker Desktop and the Docker Engine in WSL2 on Windows, Docker Desktop and Colima on macOS, and the native engine on Linux. Installing Docker covered the first install; here you learn how the pieces fit, and how to tune them.

The layers on each system

flowchart TB
    subgraph LIN["Linux"]
        direction TB
        L1["docker CLI"] --> L2["dockerd"] --> L3["Linux kernel"]
    end
    subgraph WIN["Windows"]
        direction TB
        W1["docker CLI (Windows or WSL)"] --> W2["Docker Desktop backend"] --> W3["WSL2 utility VM<br/>Linux kernel + dockerd"]
    end
    subgraph MAC["macOS"]
        direction TB
        M1["docker CLI"] --> M2["Docker Desktop / Colima"] --> M3["Linux VM<br/>kernel + dockerd"]
    end

Only on Linux does the CLI reach the engine without a virtual machine in between.

In all three cases the docker CLI is the same program, and what changes is where it sends its requests. A context names that destination. Here is a real session on Windows with Docker Desktop:

CONSOLE
$ docker context ls
NAME              DESCRIPTION                               DOCKER ENDPOINT
default           Current DOCKER_HOST based configuration   npipe:////./pipe/docker_engine
desktop-linux *   Docker Desktop                            npipe:////./pipe/dockerDesktopLinuxEngine

$ docker info --format 'OS={{.OperatingSystem}} | Kernel={{.KernelVersion}} | CPUs={{.NCPU}}'
OS=Docker Desktop (containerized) | Kernel=6.18.54.1-microsoft-standard-WSL2 | CPUs=6

The star marks the active context, desktop-linux, which points at a named pipe that Docker Desktop provides. The kernel string reveals the hidden VM: a Microsoft-built WSL2 Linux kernel. You can have several contexts (a local engine, a remote server over SSH) and switch with docker context use <name>. The engine's address can also come from the DOCKER_HOST environment variable, which overrides the context.

Windows: Docker Desktop and WSL2

WSL2 (Windows Subsystem for Linux, version 2) is a real Linux kernel running in a lightweight, managed VM, started and stopped by Windows in a second or two. It is the recommended foundation for Docker on Windows. There are two ways to use it.

Docker Desktop with the WSL2 backend. You install Docker Desktop, which creates a hidden WSL distribution (called docker-desktop) that runs the engine. Windows programs and your own WSL distributions both get a working docker command, once you enable Settings > Resources > WSL integration for each distribution. Desktop adds a dashboard, Kubernetes, extensions and update management. It is the easiest path.

CONSOLE
> wsl --list --verbose
  NAME              STATE           VERSION
* Ubuntu            Stopped         2
  docker-desktop    Running         2

(Real output, from PowerShell. VERSION 2 means a WSL2 distribution, and Stopped is normal: WSL distributions shut down when idle.)

The engine inside your own WSL distribution. In an Ubuntu WSL distribution with systemd enabled you can install Docker Engine the same way as on a Linux server (see Installing Docker), with no Desktop at all. It is lighter, has no licence considerations, and is closest to a real server, at the cost of managing it yourself.

Older setups used a Hyper-V backend, which runs a full Hyper-V VM instead. Choose it only if WSL2 is unavailable. Docker Desktop on Windows can also switch to Windows containers (a different kernel and a different set of images); this track covers Linux containers only.

Give the VM a budget

The WSL2 VM can grow to use a large share of your RAM and gives memory back slowly. Cap it with a .wslconfig file in your Windows user folder (C:\Users\<you>\.wslconfig):

INI
[wsl2]
memory=8GB
processors=4
swap=2GB

Apply it with wsl --shutdown and start Docker Desktop again. If docker info shows a different NCPU than you expect, or the machine feels sluggish with containers running, this is the first file to look at. With the Hyper-V or macOS setups the same limits are in Docker Desktop's Settings > Resources.

The file-sharing trap

A VM cannot read your host's files directly. When you write -v "$PWD":/app, the engine inside the VM has to reach your Windows or macOS folder through a file-sharing layer, which is much slower than a local disk, especially for many small files: node_modules, vendor, .git, caches.

This was measured on the Windows machine used to write this track. Each run created 3,000 tiny files from inside an Alpine container:

Where the files live Time for 3,000 small files
Container's own filesystem under 1 s
Named volume 1 s
Bind mount of a Windows folder 12 s

(One run, one machine; your numbers differ, the ranking does not.) A bind mount of a folder from the Windows side was the slowest by far, and the gap grows with the number of files. The remedies, in order of effectiveness:

  1. Keep the project inside the Linux filesystem. On Windows, clone and work in your WSL home (~/projects/app, not /mnt/c/Users/...). Reach those files from Windows through \\wsl.localhost\Ubuntu\home\<you>\projects or, better, edit them with VS Code's WSL extension, which runs the editor's server inside Linux. Bind-mounting ~/projects/app into a container is then fast, because both sides are Linux.
  2. Put heavy, generated directories in volumes, not bind mounts. Mount your source code from the host, but give node_modules (or vendor, .venv) its own named volume so thousands of dependency files never cross the boundary. See Volumes and Bind Mounts.
  3. On macOS, use the fast file-sharing implementation (VirtioFS) in Docker Desktop's settings, which is the default on recent versions.
  4. Mount less. Mount only src/, not the whole repository with its .git history.
YAML
# compose.yaml (excerpt): code from the host, dependencies in a volume
services:
  web:
    build: .
    volumes:
      - ./src:/app/src
      - node_modules:/app/node_modules
volumes:
  node_modules:

macOS: Docker Desktop, Colima and friends

On a Mac you also have a choice of "Linux VM managers", all of which provide the same docker command:

Option What it is Good for
Docker Desktop Official app: VM, dashboard, updates, Kubernetes, Compose Most people; easiest start
Colima Free, command-line tool built on Lima VMs; runs Docker (or containerd) Terminal users who want no GUI and small footprint
OrbStack Fast, polished commercial app for macOS Speed and low resource use
Rancher Desktop Open-source desktop app with dockerd or containerd An open-source GUI
Podman Desktop GUI for Podman, a daemonless Docker-compatible engine Users who prefer Podman

Colima is a good illustration of how little magic there is. Install it with Homebrew together with the CLI and Compose, start the VM, and use Docker as usual (read-only example, macOS):

CONSOLE
$ brew install colima docker docker-compose
$ colima start --cpu 4 --memory 8 --disk 60 --vm-type vz --mount-type virtiofs
$ docker context ls          # a 'colima' context is created and selected
$ docker run --rm hello-world
$ colima status
$ colima stop                # frees the memory; containers and images stay on disk

--cpu, --memory and --disk are the VM's budget, --vm-type vz uses Apple's own virtualization framework, and --mount-type virtiofs selects the fast file sharing. Because Compose is a separate plugin here, tell Docker where to find it by adding "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"] to ~/.docker/config.json (the Homebrew caveats print the exact path). colima delete removes the VM and everything in it, so back up volumes first.

Apple silicon. An M-series Mac is an arm64 machine, so the VM runs arm64 Linux, and containers run arm64 images natively. An image published only for linux/amd64 runs under emulation (QEMU or Rosetta), which works but is slower and sometimes flaky. Build multi-architecture images for your own projects (Multi-Platform Builds) and use --platform linux/amd64 only when you need to reproduce an amd64 server.

Linux

On Linux you install Docker Engine from Docker's apt/dnf repository and run it as a systemd service, as described in Installing Docker. There is no VM, so bind mounts are as fast as the disk. Two variations are worth knowing:

  • Rootless mode runs the daemon and containers as an ordinary user, reducing what a container escape could do. Some features (low ports, some network drivers) need extra setup.
  • Docker Desktop for Linux exists too. It runs the engine in a VM for parity with other systems, and its contexts coexist with the native engine.

Docker Engine, Docker Desktop, CE/EE and licensing

"Docker" names several different products, and mixing them up is the main source of licensing confusion.

Name What it is Where it runs
Docker Engine (the daemon dockerd, with containerd and runc) The open-source container runtime. "Docker CE" (Community Edition) in older docs meant this. Natively on Linux
Docker CLI, Buildx, Compose Client tools that talk to an engine. Open source. Anywhere
Docker Desktop A packaged app: a Linux VM, an engine inside it, the CLI, a dashboard, Kubernetes, Docker Scout, extensions, Model Runner and more. Windows, macOS, Linux
Docker Hub A registry service with its own plan limits (Docker Hub in Depth). Cloud

You can check which one you are talking to. On the machine used for this course:

TEXT
$ docker version --format '{{.Client.Version}} / {{.Server.Platform.Name}}'
29.8.1 / Docker Desktop
$ docker info --format '{{.OperatingSystem}}'
Docker Desktop (containerized)

On a plain Linux server the second line shows the distribution name instead.

A short history

Docker Inc. used to publish Docker CE (free) and Docker EE (paid, with support). In 2019 it sold the enterprise business to Mirantis, which sells it today as Mirantis Container Runtime. The "CE" suffix disappeared from package names, and the engine is now just Docker Engine. Docker Inc. concentrates on developer products such as Desktop, Hub, Build Cloud and Scout.

Licensing in practice

The engine is open source (Apache 2.0). Running it on Linux servers, in CI, in production, or in a Linux VM you manage yourself costs nothing. Docker Desktop is a separate commercial product with a subscription agreement: it is free for personal use, education, non-commercial open source and small businesses (the threshold is based on employee count and revenue), while larger companies need a paid plan. The thresholds and plan names change, so read the current terms on docker.com before you roll Desktop out across a company.

If a company cannot or will not pay, the usual alternatives are:

  • Linux or a Linux VM: install Docker Engine from Docker's repository (Installing Docker). On Windows you can do this inside WSL2 with systemd enabled, and use the CLI from there.
  • Colima (macOS/Linux): a small VM with Docker or containerd, described above.
  • Rancher Desktop, Podman Desktop, OrbStack: other desktop apps with their own licenses. Podman is a daemonless, mostly CLI-compatible engine (Runtimes and OCI).

Because images follow the OCI standard, an image you build with any of these runs on all the others. The licensing question is only about the tool on your laptop, not about your containers.

Practical tips

  • docker info first. When something behaves strangely, check docker context ls and docker info: you may be talking to a different engine than you think (a stopped Colima, a remote context, a different Desktop).
  • Ports are forwarded. A port published from a container (-p 8080:80) is forwarded from the VM to localhost, so http://localhost:8080 works from the host on every system.
  • host.docker.internal is a name that reaches the host from a container on Docker Desktop. On Linux you add it yourself with --add-host=host.docker.internal:host-gateway.
  • Disk space lives inside a virtual disk that can grow and often does not shrink by itself. Run docker system df and clean up with Cleaning Up; Desktop's Troubleshoot > Clean / Purge data resets everything.
  • Licensing. Docker Desktop is free for personal use, education, open source and small businesses, but larger organizations need a paid subscription. Check the current terms; Docker Engine on Linux and Colima do not have this condition.
  • CI is Linux. Whatever you use locally, most CI systems and servers run the native engine, which is why file-sharing performance is a local-only concern.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does Docker on Windows and macOS always involve a virtual machine?

    Containers are a Linux kernel feature. Docker Desktop, Colima and similar tools run a Linux VM and the engine inside it.
  2. 2. A Node project is slow in a container on Windows when you run it from C:\Users\you\app with -v mounted. What is the best fix?

    Crossing the Windows-to-VM file-sharing layer is slow for many small files. Files stored inside the Linux filesystem, or in a volume, are accessed at native speed.
  3. 3. What does a Docker context do?

    docker context use <name> redirects the CLI to another engine without changing any command. docker context ls shows the available ones.
  4. 4. You set memory=8GB in .wslconfig. What must you do for it to take effect?

    The WSL2 VM reads .wslconfig only when it starts. Shutting it down makes the next start use the new settings.
  5. 5. On an Apple silicon Mac you pull an image that exists only for linux/amd64. What happens?

    The VM is arm64, so amd64 binaries need QEMU or Rosetta emulation. Prefer multi-architecture images.

Summary

  • Outside Linux, Docker runs in a hidden Linux VM; the docker CLI talks to it through a context.
  • On Windows use Docker Desktop with the WSL2 backend (or Docker Engine inside WSL2); cap its resources in .wslconfig and restart with wsl --shutdown.
  • On macOS choose Docker Desktop, Colima, OrbStack, Rancher Desktop or Podman Desktop; Colima is a free command-line option (colima start --cpu --memory --disk).
  • File sharing between host and VM is the main performance trap: a measured bind mount of Windows files was about 12 times slower than a volume. Keep projects in the Linux filesystem and dependencies in volumes.
  • Apple silicon runs arm64 images natively; amd64 images need emulation.
  • On Linux the native engine has no VM and no file-sharing penalty.

Next: Understanding Images