Install Docker Desktop & Docker Engine

Before you can run containers you need two things: the Docker Engine, a background service (also called the daemon) that builds images and runs containers, and the Docker CLI, the docker command you type. On Windows and macOS both come inside Docker Desktop. On a Linux server you install Docker Engine directly.

This lesson covers all three systems. Follow the section for your computer, then finish with the checks at the end, which are the same everywhere.

Which one should you install?

Windows: Docker Desktop with WSL 2

Docker Desktop runs Linux containers inside WSL 2 (Windows Subsystem for Linux), so set that up first. You need 64-bit Windows 11 (version 23H2 or later) or Windows 10 version 22H2, at least 8 GB of memory, and hardware virtualization turned on in the BIOS or UEFI settings. Most laptops sold in the last few years have it on already. Windows Home works fine for Linux containers.

Open PowerShell as administrator and run:

wsl --install
wsl --update
wsl --version

wsl --install turns on the WSL feature and installs Ubuntu by default. Restart Windows when it asks. wsl --update brings WSL to its latest version (Docker Desktop needs WSL 2.1.5 or later), and wsl --version shows what you have.

Next:

1. Download Docker Desktop for Windows from the official site, docs.docker.com.
2. Run Docker Desktop Installer.exe. Keep Use WSL 2 instead of Hyper-V selected.
3. Start Docker Desktop from the Start menu and accept the subscription terms.
4. In Settings > Resources > WSL integration, turn on integration for your Ubuntu distribution. Now the docker command works both in PowerShell and inside your Ubuntu terminal.

The whale icon in the system tray turns steady when the engine is running. If Docker Desktop says virtualization is not enabled, restart into the BIOS and turn on the option called Intel VT-x, AMD-V or SVM.

macOS: Docker Desktop for Mac

Docker Desktop supports the current macOS version and the two before it, and needs at least 4 GB of memory.

1. Check your chip: Apple menu > About This Mac. It says Apple M1/M2/M3/M4... (Apple silicon) or Intel.
2. Download the matching Docker Desktop .dmg file from docs.docker.com.
3. Open it and drag Docker into Applications.
4. Start Docker from Applications and accept the terms.

On Apple silicon, images are built for the arm64 CPU type by default. Most official images support both arm64 and amd64, so this is rarely a problem. You will learn about image platforms in Docker Images & Tags.

Linux: Docker Engine on Ubuntu

On a server, install Docker Engine from Docker's own apt repository. Ubuntu's own docker.io package works but is usually older. Docker's repository supports Ubuntu 22.04, 24.04 and 26.04 LTS. If you installed docker.io, docker-compose or podman-docker from Ubuntu before, remove them first with sudo apt remove.

The steps are: download Docker's signing key, add the repository, then install the packages.

# 1. Tools and Docker's signing key
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 2. Add the repository in the deb822 .sources format
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

# 3. Install Engine, CLI, containerd and the Buildx and Compose plugins
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

The signing key lets apt check that packages really come from Docker. The $(...) parts fill in your Ubuntu code name and CPU type automatically. The service starts by itself after installation, and starts again at every boot.

Run docker without sudo

By default only root can talk to the Docker daemon. To use docker as your normal user, add yourself to the docker group, then log out and log in again (or run newgrp docker in the current terminal):

sudo usermod -aG docker $USER
newgrp docker

Docker also offers a convenience script at get.docker.com. It is handy for a throwaway test machine, but the Docker docs recommend the repository method for production, because you can see and control every step.

Check your installation

These commands work the same on every system. First check the versions of the CLI and the Compose plugin:

docker --version
docker compose version

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

Your numbers will be different, and that is fine, as long as Docker is version 29 or newer and the second command works. Then run the official test image:

docker run hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
17eec7bbc9d7: Pull complete
Digest: sha256:56433a6be3fda188089fb548eae3d91df3ed0d6589f7c2656121b911198df065
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

Docker could not find the image on your computer, so it downloaded (pulled) it from Docker Hub, started a container, and the container printed a message and exited. If you see "Hello from Docker!", your setup works.

Common mistakes

• "Cannot connect to the Docker daemon". On Windows and macOS, Docker Desktop is not running yet; start it and wait for the whale icon to settle. On Linux, check the service with sudo systemctl status docker.
• "permission denied while trying to connect to the Docker daemon socket". On Linux, you added yourself to the docker group but did not log out and in again.
• Running docker-compose with a hyphen. That is the old Compose v1 program. The current command is docker compose, with a space. See Old vs New.
• Installing two Docker versions. Remove Ubuntu's docker.io before adding Docker's repository, or the packages fight each other.

Key points

• Docker Desktop (Windows and macOS) bundles the engine in a small Linux VM, plus the CLI, Compose and a dashboard.
• On Windows, set up WSL 2 with wsl --install and wsl --update, then choose the WSL 2 backend.
• On Ubuntu servers, install docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin and docker-compose-plugin from Docker's apt repository.
• Adding a user to the docker group is the same as giving them root access.
• docker --version, docker compose version and docker run hello-world confirm that everything works.

docker --version
docker compose version
docker run hello-world
docker image ls

IMAGE                ID             DISK USAGE   CONTENT SIZE   EXTRA
hello-world:latest   56433a6be3fd       20.3kB         3.96kB   U