Installing Docker

Installing Docker is usually ten minutes of clicking. The parts worth reading first are which Docker you should install, whether your employer needs to pay for it, and the three things that go wrong on nearly every machine.

Pick your platform for the step-by-step:

• Install Docker on Windows: Docker Desktop with the WSL 2 backend
• Install Docker on macOS: Intel and Apple Silicon
• Install Docker on Linux: Docker Engine from the official repository

Docker Desktop is not the only option

"Installing Docker" means different things on different systems, and the distinction matters both technically and commercially.

Docker Engine is the daemon that actually builds and runs containers. It is open source, runs natively on Linux, and is all a server needs.

Docker Desktop bundles that engine with a Linux virtual machine, a GUI, Docker Compose, a Kubernetes cluster and an update mechanism. On Windows and macOS it is effectively required, because containers are a Linux kernel feature and those systems need a Linux VM to provide one.

The licensing question

This catches teams out, so it is worth stating plainly. Docker Desktop requires a paid subscription for commercial use in organisations above a size threshold, at the time of writing, more than 250 employees or more than $10 million in annual revenue. Below that, and for personal use, education and open source, it remains free.

Docker Engine itself is Apache 2.0 licensed and free in all cases. The licence attaches to the Desktop product, not to containers or the engine.

If the subscription is a problem, the common alternatives are:

Most of these expose a Docker-compatible socket, so docker commands, Compose files and Testcontainers generally work unchanged.

Requirements

Windows: Windows 10 or 11, 64-bit, build 19041 or later. WSL 2 enabled. Hardware virtualisation enabled in BIOS or UEFI. 4 GB RAM minimum, 8 GB realistic.

macOS: macOS 12 or newer. Intel or Apple Silicon; the installer differs, so download the right one. 4 GB RAM minimum.

Linux: a 64-bit distribution with a reasonably current kernel. 2 GB RAM. You need sudo for the install and for the post-install group change.

Verify the installation

Three commands, in order. Each one rules out a different failure.

docker --version

That only proves the CLI is on your PATH. The next one proves the daemon is running and reachable:

docker info --format '{{.ServerVersion}} {{.OperatingSystem}}'

Then confirm it can actually pull and run something:

docker run --rm hello-world

That single command exercises the registry connection, the image store, the container runtime and networking. If it works, your installation is sound.

Compose ships with current Docker as a plugin. Note it is docker compose, two words, not the old docker-compose binary:

docker compose version

The three failures almost everyone hits

1. "permission denied" on the socket (Linux)

The daemon socket is owned by root. Rather than prefixing every command with sudo, add yourself to the docker group:

sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world

newgrp applies the change to the current shell; otherwise log out and back in. Group membership is read at login, which is why "I already ran usermod" and "it still fails" are both true at the same time.

Be aware of what this grants: the docker group is effectively root on the host, since anyone in it can mount the host filesystem into a privileged container. On a shared machine, consider rootless mode instead.

2. "Cannot connect to the Docker daemon"

The CLI works and nothing is listening. On Linux the service is not started:

sudo systemctl status docker
sudo systemctl enable --now docker

On Windows or macOS, Docker Desktop is not running. Launch it and wait for the whale icon to stop animating. The CLI is installed by the same package, so it is available long before the VM has booted.

3. Virtualisation disabled (Windows)

Check whether Windows can see it:

systeminfo | findstr /C:"Virtualization"

If it reports No, enable Intel VT-x or AMD-V in your BIOS or UEFI, often labelled SVM Mode on AMD boards. Then confirm WSL 2 is present and current:

wsl --install
wsl --set-default-version 2
wsl --status

After it works

Two settings worth changing straight away on Docker Desktop.

Resource limits. Desktop's VM claims a fixed slice of CPU and memory. The defaults are conservative for real builds and generous if you only run the occasional container. Adjust under Settings → Resources.

Disk reclamation. Images, build cache and dangling volumes accumulate quickly, and the VM's disk does not shrink on its own:

docker system df

docker system prune -a --volumes

That removes every stopped container, unused image, unused network and unused volume. It is safe in the sense that running containers are untouched, and destructive in the sense that --volumes deletes data you have not explicitly kept. Read the confirmation prompt.

Key takeaways

• Docker Engine and Docker Desktop are different products. The engine is free everywhere; the licence applies to Desktop.
• Desktop needs a paid subscription above roughly 250 employees or $10M revenue. Free below that, and for personal, education and open source use.
• Linux runs containers natively. Windows and macOS run a Linux VM underneath, which is why Desktop exists.
• docker run --rm hello-world exercises registry, storage, runtime and networking in one command.
• permission denied on Linux means add yourself to the docker group, and that group is effectively root.
• "Cannot connect to the daemon" means the CLI is fine and nothing is listening. Start the service or the Desktop app.
• Run docker system df occasionally. Reclaimable space reaching double-digit gigabytes is normal and unprompted.

Check your understanding

<MCQExercise exercise={{ id: 'docker-install-group', title: 'Permission denied that survives usermod', description: 'On Ubuntu, docker run fails with "permission denied ... /var/run/docker.sock". You run sudo usermod -aG docker $USER and try again in the same terminal. It still fails. Why?', options: [ { id: 'a', text: 'Group membership is resolved at login, so the current shell still has the old set. Log out and back in, or run newgrp docker' }, { id: 'b', text: 'usermod needs the daemon restarted before the group takes effect' }, { id: 'c', text: 'The docker group must be created manually before usermod can add anyone to it' }, { id: 'd', text: 'Docker on Linux always requires sudo; the group only affects Docker Desktop' }, ], correctId: 'a', explanation: 'Supplementary groups are attached to your session when you log in, so a shell that was already open keeps the group list it started with no matter what usermod writes to /etc/group. Running newgrp docker starts a shell with the new membership, and a full logout and login fixes every shell. Worth knowing what it grants: membership of the docker group lets you mount the host filesystem into a privileged container, which is equivalent to root on that machine.', wrongExplanations: { b: 'The daemon is unaffected. What changed is your own session, and only a new session picks it up.', c: 'The docker package creates the group during installation.', d: 'Group membership is exactly how Docker on Linux is used without sudo. It is the standard post-install step.', }, }} />