Install Docker on Linux: Step-by-Step Guide for Ubuntu, CentOS, and More

Introduction / Why This Is Needed

Docker is a containerization platform that allows you to package applications and their dependencies into isolated environments. Installing Docker on Linux is the first step towards developing, testing, and deploying modern cloud applications. After completing this guide, you will be able to run containers, create images, and use the entire Docker ecosystem toolset.

Requirements / Preparation

Before you begin, ensure that:

• You have access to an account with sudo privileges (or root).
• The system is connected to the internet to download packages.
• Your distribution is supported by Docker (see the appliesTo list above).
• Basic utilities are installed: curl, gnupg (for Ubuntu/Debian) or yum-utils (for CentOS/RHEL).

Removing Conflicting Packages (Optional)

If Docker was previously installed from your distribution's repository (e.g., the docker.io package), remove it:

# For Ubuntu/Debian
sudo apt-get remove docker docker-engine docker.io containerd runc

# For CentOS/RHEL/Fedora
sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

Step-by-Step Instructions

Instructions vary depending on your distribution. Select the appropriate section.

For Ubuntu / Debian

Step 1: Install Dependencies and Add the Repository

# Update package index
sudo apt-get update

# Install necessary packages for working with HTTPS repositories
sudo apt-get install ca-certificates curl gnupg

# Create directory for keys (if it doesn't exist)
sudo install -m 0755 -d /etc/apt/keyrings

# Import Docker's GPG key (official method)
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker's repository (replace `jammy` with your version, e.g., `focal`, `noble`)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Step 2: Install Docker Engine

# Update package cache from the new repository
sudo apt-get update

# Install the latest version of Docker and its dependencies
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

For CentOS / RHEL / Fedora

Step 1: Install yum-utils and Add the Repository

# For CentOS/RHEL 7/8
sudo yum install -y yum-utils

# For Fedora (uses dnf)
sudo dnf install -y dnf-plugins-core

# Add the stable Docker repository
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
# Or for Fedora:
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

Step 2: Install Docker Engine

# Install the latest version (for CentOS/RHEL/Fedora)
sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# If yum reports conflicts, you can try:
sudo yum install docker-ce --allowerasing

For Arch Linux

# Install from official Arch repositories
sudo pacman -S docker

# Optionally install docker-compose (if a separate package is needed)
sudo pacman -S docker-compose

Common Steps for All Distributions

Step 3: Configure Permissions and Start the Service

# Add the current user to the `docker` group (to avoid using sudo)
sudo usermod -aG docker $USER

# Start the Docker daemon and enable autostart
sudo systemctl start docker
sudo systemctl enable docker

# Check status (should be `active (running)`)
sudo systemctl status docker

⚠️ Important: Group changes take effect after logging out and back in, or by running newgrp docker.

Step 4: Verify the Installation

# Download and run the `hello-world` test container
docker run hello-world

# Expected output: a message confirming the image was pulled and a hello message.

Verification

A successful installation is confirmed by:

1. The docker version command shows client and server versions without errors.
2. The hello-world container runs and displays the welcome message.
3. The Docker daemon is active: sudo systemctl is-active docker returns active.
4. The current user can run docker ps without sudo.

Potential Issues

Error: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"

Cause: The Docker daemon is not running or the current user is not in the docker group.

Solution:

sudo systemctl start docker
# Add the user to the group if you haven't already
sudo usermod -aG docker $USER
# Log out and back in, or run:
newgrp docker

Error: GPG key not found or NO_PUBKEY

Cause: Docker repository's key is not installed or added.

Solution (Ubuntu/Debian): Ensure the key is copied to /etc/apt/keyrings/docker.gpg and has a+r permissions. For older versions (pre-Ubuntu 22.04), you may need:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys <KEY_ID>

But the method using /etc/apt/keyrings is preferred.

Error: Error: failed to solve: ... when trying to run

Cause: Insufficient disk space or network issues when pulling the image.

Solution: Check free space (df -h) and connectivity to Docker Hub. You can try cleaning up old images: docker system prune -a.

containerd Version Conflict

Cause: Some distributions (especially CentOS 7) have a pre-installed containerd version that is too old.

Solution: Remove the system containerd before installing Docker (it will be installed as a dependency). Alternatively, use Docker's official script for manual installation.

Additional Configuration (Optional)

Configuring DNS for Containers

If containers cannot resolve names, edit /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

After making changes, restart the daemon: sudo systemctl restart docker.

Increasing Image Size Limits (for Production)

For production environments, it is recommended to configure the storage driver (e.g., overlay2) and resource limits. See Docker's official documentation on daemon configuration.

Final Recommendations

Now that Docker is installed, you can:

1. Learn basic commands: docker pull, docker run, docker ps, docker exec.
2. Write your first Dockerfile and build an image.
3. Install Docker Compose for orchestrating multi-container applications (included in the docker-compose-plugin package).

To update Docker in the future, use your standard package manager (apt upgrade, yum update). Regularly check for security updates.