Table of Contents

Installing Docker

There are two distinct products. Docker Engine is the daemon and CLI, runs natively on Linux, and is what servers use. Docker Desktop bundles the engine with a VM, a GUI, and Kubernetes, and is how you run Docker on Windows and macOS.

Important

Docker Desktop requires a paid subscription for commercial use in larger organizations — Docker's terms set thresholds on employee count and annual revenue. Docker Engine on Linux is free under the Apache 2.0 license and carries no such requirement. Check the current terms before deploying Desktop across a company.

Ubuntu and Debian

  1. Install the packages needed to fetch a repository over HTTPS:

    sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

  2. Determine the correct upstream distribution and codename. Docker publishes repositories for ubuntu and debian only — derivatives such as Linux Mint, Pop!_OS, Zorin, and elementary must use their upstream's repository:

    . /etc/os-release

case "$ID" in
  ubuntu|debian)
    DISTRO="$ID"; CODENAME="$VERSION_CODENAME" ;;
  *)
    # Ubuntu derivatives carry UBUNTU_CODENAME; Debian derivatives do not
    if [ -n "${UBUNTU_CODENAME:-}" ]; then
      DISTRO="ubuntu"; CODENAME="$UBUNTU_CODENAME"
    else
      DISTRO="debian"; CODENAME="$VERSION_CODENAME"
    fi ;;
esac

echo "Using https://download.docker.com/linux/$DISTRO ($CODENAME)"

  3. Add Docker's GPG key:

    sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL "https://download.docker.com/linux/$DISTRO/gpg" \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

  4. Add the repository:

    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/$DISTRO $CODENAME stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  5. Install the engine, CLI, and plugins:

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

    docker-compose-plugin provides docker compose; docker-buildx-plugin provides docker buildx. Both are needed — see Docker Compose and Building Images.

Tip

Before running step 4, sanity-check that the repository exists for your resolved values. A 404 here is the cause of the "Release file" error in Troubleshooting:

curl -sS -o /dev/null -w "%{http_code}\n" \
  "https://download.docker.com/linux/$DISTRO/dists/$CODENAME/Release"

Debian derivatives that are not Ubuntu-based — Kali, Raspberry Pi OS, Devuan — report their own codename and have no UBUNTU_CODENAME. Set CODENAME manually to the Debian release the distribution is built on (for example bookworm or trixie).

RHEL, CentOS, and Fedora

  1. Install the repository management plugin:

    sudo dnf -y install dnf-plugins-core

  2. Add the Docker repository, matching your distribution:

    # RHEL
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

# CentOS / CentOS Stream
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Fedora
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

  3. Install:

    sudo dnf install -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin

  4. Start it — unlike the Debian packages, the RPM packages do not start the service:

    sudo systemctl enable --now docker
Note

On Fedora 41+ and other dnf5 systems, dnf config-manager --add-repo has been replaced by dnf config-manager addrepo --from-repofile=<url>. If the older form errors, use the new syntax.

Older guides also install device-mapper-persistent-data and lvm2 here. Those were dependencies of the devicemapper storage driver, which has been removed — overlay2 is the driver in use today and needs neither. See Storage Drivers.

Convenience Script

For a throwaway VM or a lab machine, Docker's script handles detection for you:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

It installs the engine plus the Compose and buildx plugins. Docker does not recommend it for production hosts, since it always installs the newest release and gives you no control over versions.

Post-Installation

Run Docker Without sudo

sudo usermod -aG docker "$USER"
newgrp docker      # or log out and back in
docker run hello-world
Warning

Membership in the docker group is equivalent to root on the host — a member can mount the host filesystem into a privileged container. Treat it as an administrative grant. Where that is unacceptable, use rootless Docker instead, which needs no group membership at all.

Start on Boot

sudo systemctl enable --now docker
sudo systemctl status docker

Verify the Full Installation

docker --version
docker compose version
docker buildx version
docker info
docker run --rm hello-world

New installs log without limit and can fill the disk. Set a cap before running anything long-lived — see Daemon Configuration for the full reference:

{
  "log-driver": "local",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

sudo systemctl restart docker

Troubleshooting

Repository does not have a Release file

E: The repository 'https://download.docker.com/linux/linuxmint xia Release' does not have a Release file.

The repository URL or codename does not exist. This almost always means an Ubuntu or Debian derivative was detected as its own distribution — Docker publishes repositories for ubuntu and debian only. Use the detection in step 2, which maps derivatives to their upstream, and verify with the curl check above.

For a worked example on Proxmox, see Proxmox Docker Repository Troubleshooting.

Cannot connect to the Docker daemon

sudo systemctl status docker
sudo systemctl start docker
sudo journalctl -u docker -n 50

If the daemon refuses to start after a configuration change, validate the config:

sudo dockerd --validate --config-file /etc/docker/daemon.json

Permission denied on /var/run/docker.sock

groups                              # is "docker" listed?
sudo usermod -aG docker "$USER"
newgrp docker

The group change does not apply to shells that were already open.

Conflicting packages on Ubuntu and Debian

Distribution-packaged Docker (docker.io, docker-doc, podman-docker) conflicts with Docker's own packages. Remove them first:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt-get remove -y "$pkg"
done

docker compose not found

Compose v2 is a CLI plugin, not a docker-compose binary. Install docker-compose-plugin and invoke it as docker compose — see Docker Compose — Installation.

Next Steps

Edit this page