Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 111 ยท Getting Started

Installing Docker

Install Docker Desktop on Windows, macOS and Linux or Docker Engine on a Linux server, set up rootless mode, and verify the installation with docker version and hello-world.

There are two main ways to get Docker. On a laptop or desktop you install Docker Desktop, a single application that includes everything. On a Linux server you install Docker Engine from your distribution's package repository. Both give you the same docker command, so everything after this lesson works identically.

This lesson explains what each option installs, walks through the steps at a high level, shows the optional rootless mode, and then teaches the three commands that prove your installation works. Install steps change slightly between releases, so treat the installation commands here as a guide and check your platform's current instructions where we say so.

What you are installing

Docker is made of several cooperating parts. You will meet them in detail in How Docker Works; for installing you only need to know the names:

Part What it is
docker (the CLI) The command you type. It sends requests to the daemon.
dockerd (the daemon, "Docker Engine") A background service that builds images and manages containers.
containerd and runc Lower-level components the daemon uses to start containers.
Docker Compose The docker compose plugin for multi-container applications.
Docker Buildx The docker buildx plugin for modern image builds (BuildKit).

Docker Desktop installs all of these, plus a graphical dashboard and (on Windows and macOS) the Linux virtual machine in which your containers run. Docker Engine on Linux installs the same components without the dashboard and without a VM.

Option 1: Docker Desktop (Windows, macOS, Linux)

Docker Desktop is the easiest path for development machines.

Windows. You need Windows 10 or 11 (64-bit) with hardware virtualization enabled in the BIOS/UEFI. Docker Desktop uses the WSL 2 backend (Windows Subsystem for Linux, a lightweight VM managed by Windows) by default, which is fast and uses memory dynamically. Download the installer from the Docker website, run it, accept the WSL 2 option when asked, and restart if prompted. Then start "Docker Desktop" from the Start menu and wait until its status says the engine is running.

macOS. Download the right installer for your chip (Apple silicon or Intel), drag Docker into Applications and start it. The first launch asks for permission to install a helper component.

Linux. Docker Desktop for Linux exists too, but most Linux users prefer plain Docker Engine (below) because it has no VM layer and is easier to automate.

Docker Desktop has licensing terms: it is free for personal use, education and small businesses, but larger companies need a paid subscription. Docker Engine on Linux is open source and free for everyone. If your employer has a policy, check it before installing.

After installation, open a terminal (PowerShell, Windows Terminal, Terminal.app or any shell) and continue with the verification steps below. Nothing here requires administrator rights once Docker Desktop is running.

Option 2: Docker Engine on Linux

On a Linux server you add Docker's package repository and install the packages with your package manager. The details differ by distribution, so this is a read-only example for Ubuntu or Debian; follow the current instructions for your own distribution before running anything on a real machine.

Terminal
# Read-only example: the shape of an Ubuntu/Debian install
sudo apt-get update
sudo apt-get install ca-certificates curl

# ...add Docker's signing key and apt repository (see the official instructions)...

sudo apt-get install docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

The package names tell you what you get: docker-ce is the daemon, docker-ce-cli the command, containerd.io the container runtime, and the last two are the Buildx and Compose plugins. The service is enabled and started automatically on most distributions; if it is not, start it with:

Terminal
# Read-only example
sudo systemctl enable --now docker

Avoid installing the docker.io or docker-compose packages from some distributions' own repositories without checking their versions: they can be years behind. Also avoid running the "convenience script" (curl ... | sh) on production machines. It is handy for a throwaway test VM, but it installs whatever is current without review.

Running docker without sudo

The Docker daemon listens on a Unix socket owned by root and the group docker. By default only root can talk to it, so a new user sees this error:

CONSOLE
$ docker ps
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

(The exact wording differs between versions.) The common fix is to add yourself to the docker group and start a new login session:

Terminal
# Read-only example
sudo usermod -aG docker $USER
newgrp docker

Membership of the docker group is effectively root access to the machine, because anyone who can start containers can mount the host's file system into one. Add only people you would trust with sudo. The daemon security lesson explains why, and the alternative below avoids the problem.

Option 3: Rootless mode

In rootless mode the Docker daemon and the containers run entirely as your normal user, with no root privileges at all. If a process escapes its container, it only has your user's rights. This makes it a good choice for shared machines and for people who dislike the docker group trade-off.

Rootless Docker needs a few prerequisites, mainly the uidmap package (the newuidmap and newgidmap tools) and subordinate UID/GID ranges for your user in /etc/subuid and /etc/subgid. The installer script ships with the Engine packages:

Terminal
# Read-only example
sudo apt-get install uidmap
dockerd-rootless-setuptool.sh install
systemctl --user enable --now docker
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock

Rootless mode has real limitations. Containers cannot bind host ports below 1024 unless you change a kernel setting, some storage and networking features are restricted, and performance of the network path is slightly lower. For learning and many development tasks none of this matters. We return to it in seccomp, AppArmor and Read-Only Filesystems.

Verify the installation

Whatever route you took, three commands tell you whether everything works.

1. docker version

docker version prints two blocks: the client (the command you ran) and the server (the daemon). If you see only a client block and an error about connecting, the daemon is not running.

CONSOLE
$ docker version
Client:
 Version:           29.8.1
 API version:       1.56
 Go version:        go1.26.8
 Git commit:        4a63305
 Built:             Tue Sep 15 16:28:39 2026
 OS/Arch:           windows/amd64
 Context:           desktop-linux

Server: Docker Desktop 4.93.0 (240920)
 Engine:
  Version:          29.8.1
  API version:      1.56 (minimum version 1.40)
  Go version:       go1.26.8
  Git commit:       464cd50
  Built:            Tue Sep 15 16:25:38 2026
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.3.5
 runc:
  Version:          1.5.1
 docker-init:
  Version:          0.19.0

(Shortened; yours will show your own versions and OS.) Notice that the client here runs on windows/amd64 while the server runs on linux/amd64: the CLI is a Windows program talking to the Linux daemon inside Docker Desktop's VM. On a Linux host both would say linux.

For a compact check you can ask for just the versions:

CONSOLE
$ docker version --format 'client={{.Client.Version}} server={{.Server.Version}}'
client=29.8.1 server=29.8.1

2. Compose and Buildx

The two plugins report their versions with their own subcommands:

CONSOLE
$ docker compose version
Docker Compose version v5.5.1
$ docker buildx version
github.com/docker/buildx v0.37.1 0b265a9f62db554fa9aba6dd19e1bd5704bc7d8a

Note the spelling: modern Docker uses docker compose (a space), not the old standalone docker-compose (a hyphen). All of this tutorial uses the space form.

3. docker run hello-world

hello-world is a tiny official image whose only job is to print a message. Running it exercises the whole chain: the CLI, the daemon, pulling from Docker Hub, creating and starting a container, and streaming its output back to you.

CONSOLE
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
4f55086f7dd0: Pull complete
Digest: sha256:11a3eb1597e864c51b3f56733cb2e8a90bf0c284bfc05f9444d81c558bc848aa
Status: Downloaded newer image for hello-world:latest

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

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.
...

(The remaining lines of the message are omitted. On a real terminal Docker also shows live progress bars for each layer; the Pulling fs layer and Download complete lines are replaced by them.) If you see "Hello from Docker!", you are done. Run it a second time and the first four lines disappear, because the image is now cached locally.

Check what the daemon is configured with

docker info shows how the installation is set up. A few lines are worth knowing:

CONSOLE
$ docker info --format '{{.Driver}} | cgroup v{{.CgroupVersion}} | runtime {{.DefaultRuntime}} | {{.OSType}}'
overlayfs | cgroup v2 | runtime runc | linux

This installation stores image layers with the overlayfs storage driver (the containerd image store), uses cgroup version 2 for resource limits, and runs containers with runc. If you are on a different setup, some values may be different (for example overlay2 on older Engine installs); that is fine. We explain these terms in How Docker Works and Layers and the Union Filesystem.

Troubleshooting a new installation

Symptom Likely cause and fix
Cannot connect to the Docker daemon The daemon is not running. Start Docker Desktop, or sudo systemctl start docker on Linux.
permission denied ... docker.sock Your user is not in the docker group (Linux). Use sudo, add yourself to the group, or use rootless mode.
Docker Desktop stuck on "starting" on Windows Virtualization or WSL 2 is not enabled. Run wsl --update, check virtualization in the BIOS, restart.
pull access denied or timeouts No internet access or a proxy is blocking Docker Hub. Configure the proxy in Docker Desktop settings or the daemon.
no matching manifest for ... in the manifest list entries The image has no build for your CPU (for example, an amd64-only image on an ARM machine). See Multi-Platform Images.

When something fails, copy the exact error message into a search. Docker's messages are consistent and well-documented, and you will find the cause quickly. The lesson Common Docker Errors collects the usual suspects with fixes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command proves that the Docker client can reach the daemon and that both are installed?

    docker version asks the daemon for its version, so a Server block means the connection works. If the daemon is not reachable you only get the client block plus an error.
  2. 2. What does docker run hello-world do the first time you run it?

    docker run pulls the image automatically when it is missing locally, then creates and starts a container. The second run skips the pull.
  3. 3. Why is membership of the docker group on Linux a security concern?

    The daemon runs as root. A user who controls it can run a container with the host's root directory mounted, so the group should contain only trusted users. Rootless mode avoids this.
  4. 4. What is the main idea of rootless mode?

    In rootless mode both the daemon and the containers run as an unprivileged user, so a container escape only gains that user's rights. The trade-off is some feature limits, such as privileged ports.

Summary

  • Use Docker Desktop on Windows and macOS; use Docker Engine packages on Linux servers. Both provide the same docker command.
  • Docker Desktop on Windows normally uses the WSL 2 backend and runs one hidden Linux VM for all containers.
  • On Linux, the docker group is root-equivalent; rootless mode runs the daemon and containers as an ordinary user, with some limits.
  • docker version, docker compose version and docker buildx version show what is installed; docker run hello-world tests the whole chain.
  • Use docker compose (with a space), not the old docker-compose.

Next: Your First Container