Skip to content

_index.md

Latest commit

 

History

History
247 lines (185 loc) · 10.4 KB

_index.md

File metadata and controls

247 lines (185 loc) · 10.4 KB
description Install Docker on Linux with ease using our step-by-step installation guide covering system requirements, supported platforms, and where to go next.
keywords linux, docker linux install, docker linux, linux docker installation, docker for linux, docker desktop for linux, installing docker on linux, docker download linux, how to install docker on linux, linux vs docker engine, switch docker contexts
title Install Docker Desktop on Linux
linkTitle Linux
weight 60
aliases
/desktop/linux/install/
/desktop/install/linux-install/
/desktop/install/linux/

Docker Desktop terms

Commercial use of Docker Desktop in larger enterprises (more than 250 employees or more than $10 million USD in annual revenue) requires a paid subscription.

This page contains information about general system requirements, supported platforms, and instructions on how to install Docker Desktop for Linux.

Important

Docker Desktop on Linux runs a Virtual Machine (VM) which creates and uses a custom docker context, desktop-linux, on startup.

This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux.

{{< accordion title=" Docker Desktop vs Docker Engine: What's the difference?" >}}

Important

For commercial use of Docker Engine obtained via Docker Desktop within larger enterprises (exceeding 250 employees or with annual revenue surpassing $10 million USD), a paid subscription is required.

Docker Desktop for Linux provides a user-friendly graphical interface that simplifies the management of containers and services. It includes Docker Engine as this is the core technology that powers Docker containers. Docker Desktop for Linux also comes with additional features like Docker Scout and Docker Extensions.

Installing Docker Desktop and Docker Engine

Docker Desktop for Linux and Docker Engine can be installed side-by-side on the same machine. Docker Desktop for Linux stores containers and images in an isolated storage location within a VM and offers controls to restrict its resources. Using a dedicated storage location for Docker Desktop prevents it from interfering with a Docker Engine installation on the same machine.

While it's possible to run both Docker Desktop and Docker Engine simultaneously, there may be situations where running both at the same time can cause issues. For example, when mapping network ports (-p / --publish) for containers, both Docker Desktop and Docker Engine may attempt to reserve the same port on your machine, which can lead to conflicts ("port already in use").

We generally recommend stopping the Docker Engine while you're using Docker Desktop to prevent the Docker Engine from consuming resources and to prevent conflicts as described above.

Use the following command to stop the Docker Engine service:

$ sudo systemctl stop docker docker.socket containerd

Depending on your installation, the Docker Engine may be configured to automatically start as a system service when your machine starts. Use the following command to disable the Docker Engine service, and to prevent it from starting automatically:

$ sudo systemctl disable docker docker.socket containerd

Switching between Docker Desktop and Docker Engine

The Docker CLI can be used to interact with multiple Docker Engines. For example, you can use the same Docker CLI to control a local Docker Engine and to control a remote Docker Engine instance running in the cloud. Docker Contexts allow you to switch between Docker Engines instances.

When installing Docker Desktop, a dedicated "desktop-linux" context is created to interact with Docker Desktop. On startup, Docker Desktop automatically sets its own context (desktop-linux) as the current context. This means that subsequent Docker CLI commands target Docker Desktop. On shutdown, Docker Desktop resets the current context to the default context.

Use the docker context ls command to view what contexts are available on your machine. The current context is indicated with an asterisk (*).

$ docker context ls
NAME            DESCRIPTION                               DOCKER ENDPOINT                                  ...
default *       Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                      ...
desktop-linux                                             unix:///home/<user>/.docker/desktop/docker.sock  ...

If you have both Docker Desktop and Docker Engine installed on the same machine, you can run the docker context use command to switch between the Docker Desktop and Docker Engine contexts. For example, use the "default" context to interact with the Docker Engine:

$ docker context use default
default
Current context is now "default"

And use the desktop-linux context to interact with Docker Desktop:

$ docker context use desktop-linux
desktop-linux
Current context is now "desktop-linux"

Refer to the Docker Context documentation for more details. {{< /accordion >}}

Supported platforms

Docker provides .deb and .rpm packages for the following Linux distributions and architectures:

Platform x86_64 / amd64
Ubuntu ✅
Debian ✅
Red Hat Enterprise Linux (RHEL) ✅
Fedora ✅

An experimental package is available for Arch-based distributions. Docker has not tested or verified the installation.

Docker supports Docker Desktop on the current LTS release of the aforementioned distributions and the most recent version. As new versions are made available, Docker stops supporting the oldest version and supports the newest version.

General system requirements

To install Docker Desktop successfully, your Linux host must meet the following general requirements:

  • 64-bit kernel and CPU support for virtualization.
  • KVM virtualization support. Follow the KVM virtualization support instructions to check if the KVM kernel modules are enabled and how to provide access to the KVM device.
  • QEMU must be version 5.2 or later. We recommend upgrading to the latest version.
  • systemd init system.
  • GNOME, KDE, or MATE desktop environments are supported but others may work.
    • For many Linux distributions, the GNOME environment does not support tray icons. To add support for tray icons, you need to install a GNOME extension. For example, AppIndicator.
  • At least 4 GB of RAM.
  • Enable configuring ID mapping in user namespaces, see File sharing. Note that for Docker Desktop version 4.35 and later, this is not required anymore.
  • Recommended: Initialize pass for credentials management.

Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see Why Docker Desktop for Linux runs a VM.

Note

Docker does not provide support for running Docker Desktop for Linux in nested virtualization scenarios. We recommend that you run Docker Desktop for Linux natively on supported distributions.

KVM virtualization support

Docker Desktop runs a VM that requires KVM support.

The kvm module should load automatically if the host has virtualization support. To load the module manually, run:

$ modprobe kvm

Depending on the processor of the host machine, the corresponding module must be loaded:

$ modprobe kvm_intel  # Intel processors

$ modprobe kvm_amd    # AMD processors

If the above commands fail, you can view the diagnostics by running:

$ kvm-ok

To check if the KVM modules are enabled, run:

$ lsmod | grep kvm
kvm_amd               167936  0
ccp                   126976  1 kvm_amd
kvm                  1089536  1 kvm_amd
irqbypass              16384  1 kvm

Set up KVM device user permissions

To check ownership of /dev/kvm, run :

$ ls -al /dev/kvm

Add your user to the kvm group in order to access the kvm device:

$ sudo usermod -aG kvm $USER

Sign out and sign back in so that your group membership is re-evaluated.

Using Docker SDKs with Docker Desktop

Docker Desktop for Linux uses a per-user socket instead of the system-wide /var/run/docker.sock. Docker SDKs and tools that connect directly to the Docker daemon need the DOCKER_HOST environment variable set to connect to Docker Desktop. For configuration details, see How do I use Docker SDKs with Docker Desktop for Linux?.

Verify your installation

After installing Docker Desktop, verify it is working correctly:

  1. Open a terminal and check the Docker version:
   $ docker --version

You should see output similar to:

   Docker version 27.x.x, build xxxxxxx
  1. Run the hello-world container to confirm Docker Desktop is working end-to-end:
   $ docker run hello-world

If successful, you should see:

   Hello from Docker!
   This message shows that your installation appears to be working correctly.
  1. Check that Docker Desktop is using the correct context:
   $ docker context ls

The desktop-linux context should be marked with an asterisk (*) as the active context.

Where to go next