Install Docker on Linux

You've read about containers, imagined isolated environments for your apps, but every time you try to actually run Docker, you hit a wall with installation errors, missing dependencies, or confusing package managers. Without Docker Engine properly installed on Linux, none of the rest of the container journey — images, volumes, networks — is possible. This lesson gives you a repeatable, reliable method to install Docker Engine on Linux so you can start building and shipping containers today.

The problem this lesson solves

Installing Docker Engine on Linux seems simple until you run apt-get install docker.io and end up with an outdated version, or follow a random blog post that breaks your kernel. The core pain points are:

• Out-of-repo versions: Default repositories (apt, yum) often ship very old Docker packages.
• Incomplete installs: Missing the docker-ce (Community Edition) daemon or the containerd runtime.
• Permission hell: Running docker ps without sudo fails with cryptic "permission denied" errors.
• Conflicting packages: Previous attempts leave behind broken docker, docker.io, or docker-engine packages.

This lesson eliminates those pain points by using Docker's official repository — the same source used by CI/CD pipelines and production servers.

Core concept / mental model

Think of Docker Engine as three interlocking parts, like a three-layer cake:

1. Docker daemon (dockerd) – the background service that manages containers, images, networks, and storage. It listens for API requests and does the heavy lifting.
2. containerd – the low-level container runtime that actually runs processes inside namespaces and cgroups. Docker daemon delegates to it.
3. Docker CLI (docker) – the client tool you type commands into. It talks to the daemon over a local UNIX socket (/var/run/docker.sock) or a network API.

When you install "Docker Engine," you're getting all three pieces. The CLI is your steering wheel, the daemon is the engine block, and containerd is the fuel injector.

Pro tip: Think of the Docker repository as a vending machine. Instead of hunting for packages across the internet, you add one official vending machine to your system, then pull exactly the versions you need.

How it works step by step

Installing Docker Engine on Linux follows a predictable six-step recipe, regardless of your distro (Ubuntu, Debian, CentOS, Fedora). The steps are:

1. Uninstall old versions – remove any docker, docker.io, docker-engine packages that might conflict.
2. Update package index – refresh your local package database.
3. Install prerequisites – add packages like ca-certificates, curl, gnupg, and lsb-release that make the next steps work.
4. Add Docker's official GPG key – cryptographically sign the packages so your system trusts them.
5. Add the Docker repository – point your package manager at Docker's own repo for the latest stable releases.
6. Install Docker Engine – use apt-get install docker-ce docker-ce-cli containerd.io (or the equivalent yum / dnf commands).

After installation, you must start the daemon (systemctl start docker) and verify it works (docker run hello-world). Finally, add your user to the docker group to avoid typing sudo before every command.

Pro tip: The group addition (sudo usermod -aG docker $USER) only takes effect after you log out and back in. Use newgrp docker in the same terminal session to bypass a reboot.

Hands-on walkthrough

Below are complete, runnable examples for Ubuntu/Debian and CentOS/RHEL. Follow one set based on your distro.

Example 1: Install on Ubuntu 22.04 (Debian-based)

# Step 1: Uninstall old versions
sudo apt-get remove docker docker-engine docker.io containerd runc

# Step 2: Update package index and install prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Step 3: Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Step 4: Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Step 5: Update and install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Step 6: Start and verify
sudo systemctl start docker
sudo docker run hello-world

Expected output at the end:

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

Example 2: Install on CentOS 9 (RHEL-based)

# Step 1: Uninstall old versions
sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

# Step 2: Install prerequisites
sudo yum install -y yum-utils

# Step 3: Add repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Step 4: Install Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Step 5: Start daemon and enable on boot
sudo systemctl start docker
sudo systemctl enable docker

# Step 6: Verify with non-root run (skipping sudo test)
sudo docker run hello-world

Example 3: Post-install – running Docker without sudo

After the base install, you want to avoid sudo for everyday commands:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Activate group change without logout
newgrp docker

# Verify
id -nG   # output should include 'docker'
docker run hello-world   # should work without sudo

Pro tip: If you see Got permission denied while trying to connect to the Docker daemon socket, you missed the group step or didn't reload. Run newgrp docker again.

Example 4: Verify installation with a simple container

# In your terminal, run a quick container to check everything works
import subprocess
result = subprocess.run(['docker', 'ps', '--all'], capture_output=True, text=True)
print(result.stdout)

Expected output (initially empty, but no error):

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Compare options / when to choose what

Choose the official repository for 90% of cases — it's the most maintainable. Use the convenience script for one-shot demos. Avoid the distro package unless you're on an LTS that backports (rare).

Troubleshooting & edge cases

Below are the most common issues after [install docker engine on linux] and how to fix them.

"Error: Package 'docker-ce' has no installation candidate"

Your repository configuration is missing or the architecture is wrong.

# Re-add the repository with correct architecture
sudo rm /etc/apt/sources.list.d/docker.list
echo \
  "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update

"Cannot connect to the Docker daemon"

Daemon isn't running, or your user can't access the socket.

sudo systemctl status docker   # check if active
sudo systemctl start docker    # if inactive
ls -la /var/run/docker.sock    # should be owned by root:docker
sudo usermod -aG docker $USER && newgrp docker

"docker: permission denied while trying to connect"

You haven't added your user to the docker group, or you need to log out and back in.

sudo usermod -aG docker $USER
newgrp docker

Repository not found for Ubuntu arm64 / Raspberry Pi

The official repository supports arm64, but the URL is the same. Use arch=arm64 in the deb line. For 32-bit ARM (armhf), use the same repo — Docker images exist for those platforms.

Conflict with podman or containerd

Remove them first:

sudo apt-get remove podman runc   # Debian
sudo yum remove podman containerd.io   # RHEL

What you learned & what's next

You now understand that [install docker engine on linux] means setting up the Docker daemon, containerd, and CLI from Docker's official repository. You can: - Uninstall conflicting older packages. - Add the GPG key and repository for your specific distro. - Install, start, and verify the latest Docker Engine. - Run Docker commands without sudo by joining the docker group.

This foundation unlocks the rest of the Docker learning path. In the next lesson, you'll pull your first image and run a container with custom ports and volumes. You'll take the Engine you just installed and make it actually serve an application.

Pro tip: After verifying the install, run docker info to see system-wide details — Swarm status, storage driver, CPU/memory limits, and more. It's the quickest health check.