Common Docker Installation Issues

Docker is a crucial tool for containerizing applications, and installing it on your system is the first step to using it efficiently. This post addresses common installation issues with Docker.

How to Verify if Docker is Already Installed

Before installing Docker, it’s a good idea to check whether Docker and Docker Compose are already installed.

On Linux, open your terminal, and on Windows, launch PowerShell as an administrator, then run the following commands.

docker --version

If Docker is installed, you’ll see the version number. Similarly, check for Docker Compose by running:

docker-compose --version

If both are installed, you’re ready to go!

Installing Docker


1-For Linux, This link will assist you in installing Docker on various Linux platforms.

2- For windows please download Docker Desktop from the docker official website, then run the installer as administrator and follow the instructions.

Addressing Common Docker Installation Issues in Linux

The two most common issues when installing Docker in Linux are an outdated or incompatible Linux kernel version, and insufficient user permissions. Below is an explanation of each issue, its common manifestation and how to resolve it.

1- Outdated or incompatible kernel version

The number one issue when installing Docker, particularly on Linux systems, is outdated or incompatible kernel versions. Docker requires a relatively recent version of the Linux kernel (3.10 or newer) to function correctly. Many users encounter problems when their system kernel is either too old or not properly configured to support Docker’s required features.

Common manifestations of this issue include:
  • Docker failing to start after installation.
  • Error messages related to kernel modules such as cgroup or overlay.
  • Compatibility issues on older or less frequently updated distributions.
How to resolve it:

Check the kernel version using

uname -r
  • Upgrade the kernel if necessary by updating the OS or installing a newer kernel version. Remember that Docker requires at least version 3.10 of the Linux kernel to function properly.
  • Make sure that “cgroups” and other necessary kernel features are enabled.

2- Insufficient user permissions

The second most common problem when installing Docker on Linux systems is insufficient user permissions to run Docker commands. After installing Docker, users often encounter permission errors when trying to run Docker commands without using “sudo”.

Symptoms of this issue:
  • Error messages like “Permission denied” or “Cannot connect to the Docker daemon” when running Docker commands such as docker run or docker ps.
  • Having to use “sudo” every time you run a Docker command.
How to resolve it:
  1. Add your user to the Docker group:

    Docker requires administrative privileges to manage containers. Instead of running every command with “sudo“, you can add your user to the docker group, allowing you to run Docker commands without “sudo“. Follow these steps:
sudo usermod -aG docker $USER

2. Restart your system or log out and log back in for the changes to take effect.

3. Verify the fix by running a Docker command :

docker ps

If the command runs without error, your user now has the necessary permissions to run Docker commands.

Addressing Common Docker Installation Issues in Windows

A common issue with installing Docker on Windows is having an outdated Windows version. Docker can be installed on Windows 10 Pro edition or later, or Windows 10 Home edition with WSL 2 enabled. Any earlier versions of Windows will not support Docker. Another frequent issue is missing or improperly configured virtualization support.

1- Versions of Windows prior to Windows 10

If you’re using a version of Windows prior to Windows 10, you won’t be able to install Docker without upgrading your system. Additionally, if you’re using Windows 10 Home edition, ensure that WSL 2 is enabled by running the following command in your PowerShell, which should be run as an administrator:

wsl --status

This command provides information about the current WSL configuration and whether your system is using WSL 2. 

wsl --install
wsl --set-default-version 2

The previous two commands work as follows: After running the first command, WSL will be installed on your system, and you may be prompted to restart your computer. The second command sets WSL 2 as the default version for any new Linux distributions you install.

2- Missing or misconfigured virtualization support

The second most common problem when installing Docker is missing or misconfigured virtualization support, particularly on systems where virtualization (Intel VT-x for Intel CPUs or AMD-V for AMD CPUs) is disabled in the BIOS/UEFI settings.

Symptoms of this issue include:
  • Docker installation completing, but containers failing to run.
  • Error messages like “This system doesn’t support virtualization” or “Cannot create container”.
  • Docker Desktop on Windows might fail to start with errors related to virtualization.
How to Resolve It:
1Step-by-Step Instructions to Enable Virtualization in BIOS/UEFI:

1. Restart Your Computer

  • Save all your work and restart your computer.

2. Enter BIOS/UEFI Settings

  • During the boot process, press the key required to enter BIOS/UEFI. The specific key depends on your motherboard or computer manufacturer. Common keys include:
    • F2 (most common)
    • Delete
    • F10
    • Esc

Typically, a message like “Press [Key] to enter BIOS” or “Setup” will appear briefly on the screen during startup.

3. Navigate to the Virtualization Settings

  • Once in the BIOS/UEFI menu, look for settings related to virtualization. The exact location of the setting will vary depending on your system’s manufacturer. It’s typically found under these sections:
    • Advanced or Advanced Mode
    • CPU Configuration
    • System Configuration
    • Security

Some common names for virtualization settings include:

  • Intel VT-x (for Intel CPUs)
  • Intel Virtualization Technology
  • AMD-V (for AMD CPUs)
  • SVM Mode (for AMD CPUs)

4. Enable Virtualization

  • Select the option for Intel VT-x, AMD-V, or Virtualization Technology, and set it to Enabled.
  • Use your keyboard’s function keys or arrow keys to change the setting.

5. Save and Exit BIOS/UEFI

  • After enabling virtualization, find the Save & Exit option. This is usually located under the “Exit” menu.
  • Confirm that you want to save changes and exit.
  • Your system will restart.

6. Verify Virtualization is Enabled

Once your system restarts, you can verify if virtualization is enabled:

  1. Open Task Manager (Ctrl + Shift + Esc).
  2. Go to the Performance tab.
  3. Select CPU from the left menu.
  4. In the bottom-right corner, look for Virtualization: Enabled.

If you see Enabled, you have successfully enabled virtualization.