How to Install Docker on Ubuntu, Windows (WSL2) and macOS
How to Install Docker on Ubuntu, Windows (WSL2) and macOS
Docker is the standard tool for building and running containers, and installing it correctly is the first real step in any Docker learning path. A rushed install, such as using an outdated distribution package or skipping the post-install steps, often causes permission errors, disk-space problems and confusing networking behaviour later.
This guide shows how to install Docker the way the official documentation recommends on the three platforms developers use most: Ubuntu Linux, Windows with WSL 2, and macOS on both Apple silicon and Intel. You will also learn how to verify the installation, complete the important post-install configuration, and fix the most common installation errors.
The commands in this guide are written for Docker Engine 29 and the current releases of Docker Desktop, as of October 2026.
Quick Answer
Ubuntu: add Docker's official apt repository, then run sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin.
Windows: update WSL with wsl --update, install Docker Desktop with the WSL 2 backend, then enable WSL integration for your Linux distribution.
macOS: download the Docker Desktop installer for your chip (Apple silicon or Intel), drag Docker into Applications, and start it.
Everywhere: confirm the install with docker run hello-world.
Docker Engine vs Docker Desktop: Which Should You Install?
Before installing, it helps to understand that "Docker" can mean two different products.
Docker Engine is the open-source container runtime. It consists of the Docker daemon (dockerd), the docker command-line client, containerd and plugins such as Buildx and Compose. It runs natively on Linux, which is why servers and CI machines use it.
Docker Desktop is an application for Windows, macOS and Linux desktops. It runs Docker Engine inside a lightweight Linux virtual machine and adds a graphical dashboard, automatic updates, Kubernetes, and developer tools. Windows and macOS cannot run Linux containers natively, so Docker Desktop provides that Linux environment for you.
Licensing: Docker Engine is free and open source. Docker Desktop is free for personal use, education, non-commercial open source projects and small businesses with fewer than 250 employees and less than USD 10 million in annual revenue. Larger organisations, and government entities, need a paid Docker subscription to use Docker Desktop.
Part 1: Install Docker Engine on Ubuntu
Requirements
A 64-bit version of Ubuntu 26.04 LTS (Resolute), 24.04 LTS (Noble) or 22.04 LTS (Jammy).
A supported architecture: x8664 (amd64), arm64, armhf, s390x or ppc64le.
A user account with sudo privileges and internet access.
Derivative distributions such as Linux Mint are not officially supported. Docker may still work on them, but use an official Ubuntu release for anything important.
Check your Ubuntu version and architecture with:
lsbrelease -a
dpkg --print-architecture
Step 1: Remove Conflicting Packages
Ubuntu's own repositories ship unofficial packages such as docker.io and podman-docker. These conflict with the official Docker packages, so remove them first. The command is safe to run even if none of them are installed.
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc | cut -f1)
Removing these packages does not delete existing images, containers or volumes stored in /var/lib/docker/.
Step 2: Add Docker's Official apt Repository
Installing from Docker's own repository gives you the latest stable release and makes future upgrades a normal apt upgrade. First, add Docker's GPG signing key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
Next, add the repository. This uses the modern DEB822 sources format and detects your Ubuntu codename and architecture automatically:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTUCODENAME:-$VERSIONCODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
Step 3: Install Docker Engine
Install Docker Engine, the CLI, containerd, and the Buildx and Compose plugins:
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Here is what each package provides:
To install a specific version instead of the latest, list the available versions and pass the version string to apt install:
apt list --all-versions docker-ce
VERSIONSTRING=<version-from-the-list>
sudo apt install docker-ce=$VERSIONSTRING docker-ce-cli=$VERSIONSTRING containerd.io docker-buildx-plugin docker-compose-plugin
Step 4: Verify the Installation
The Docker service starts automatically after installation. Check its status, and start it if it is not running:
sudo systemctl status docker
sudo systemctl start docker
Run the test container:
sudo docker run hello-world
Docker downloads a small test image and runs it. If you see a message beginning with "Hello from Docker!", Docker Engine is working.
Step 5: Post-Installation Setup (Recommended)
Run Docker without sudo. By default, only root can talk to the Docker daemon. To run docker commands as your normal user, add yourself to the docker group. The group usually already exists after installation; if groupadd reports that, simply continue.
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker run hello-world
Log out and back in (or restart a VM) so the group change applies to all your sessions. newgrp docker applies it to the current terminal only.
Security warning: Membership of the docker group grants root-level privileges on the host, because anyone who can control the Docker daemon can mount the host filesystem into a container. Only add trusted users. For stricter isolation, consider Docker's rootless mode.
Start Docker on boot. On Ubuntu this is already enabled, but you can make it explicit:
sudo systemctl enable docker.service
sudo systemctl enable containerd.service
Turn on log rotation. The default json-file logging driver keeps writing container logs to disk without limit, which can eventually fill the disk. The simplest fix is to switch to the local logging driver, which rotates logs by default. Create or edit /etc/docker/daemon.json:
{
"log-driver": "local"
}
Then restart Docker. The new default applies to containers created after the restart:
sudo systemctl restart docker
Firewall: Ports you publish with Docker (for example -p 8080:80) bypass ufw and firewalld rules, because Docker inserts its own packet-filtering rules. To expose a service only on the local machine, publish it on the loopback address, for example -p 127.0.0.1:8080:80. For custom filtering, add rules to the DOCKER-USER chain.
Alternative: The Convenience Script (Test Machines Only)
Docker provides a script at get.docker.com that detects your distribution and installs Docker automatically. It is useful for throwaway test or development VMs, but Docker does not recommend it for production. Preview what it will do with --dry-run before running it:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh --dry-run
sudo sh get-docker.sh
Upgrade and Uninstall
Because you installed from Docker's repository, upgrading is part of your normal system updates:
sudo apt update
sudo apt upgrade
To remove Docker completely, purge the packages and, only if you no longer need them, delete all images, containers and volumes:
sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
sudo rm /etc/apt/sources.list.d/docker.sources
sudo rm /etc/apt/keyrings/docker.asc
Warning: Deleting /var/lib/docker and /var/lib/containerd permanently removes all images, containers and volumes, including any database data stored in volumes. Back up anything you need first.
Part 2: Install Docker Desktop on Windows With WSL 2
On Windows, Docker Desktop runs Linux containers inside the Windows Subsystem for Linux 2 (WSL 2). WSL 2 uses a real Linux kernel in a lightweight virtual machine, which gives fast startup and good file-system performance when your code lives inside the Linux file system.
Requirements
Windows Server editions (such as Windows Server 2019 and 2022) are not supported by Docker Desktop. An Arm64 build of Docker Desktop for Windows is available as Early Access.
To confirm virtualisation is enabled, open Task Manager → Performance → CPU and check that Virtualization shows Enabled. If it does not, enable Intel VT-x or AMD-V (sometimes called SVM) in your BIOS/UEFI settings.
Step 1: Install or Update WSL
Open PowerShell as Administrator and check your WSL version:
wsl --version
If the command prints version details, update WSL to the latest release:
wsl --update
If it prints no version details, you have the older built-in version of WSL or none at all. Install the current version, then restart Windows if prompted:
wsl --install
On a fresh setup, wsl --install also installs Ubuntu as the default Linux distribution. To install Ubuntu explicitly, run wsl --install -d Ubuntu. Open Ubuntu from the Start menu once to create your Linux username and password.
Step 2: Download and Run the Installer
Download Docker Desktop for Windows from the official Docker website (docs.docker.com, under Docker Desktop → Install → Windows). Choose the x8664 installer unless you have an Arm-based PC.
Double-click Docker Desktop Installer.exe and follow the wizard:
Choose the installation mode. Per-user is the recommended default: it installs to your user profile, needs no administrator rights to install or update, and uses the WSL 2 backend. All users requires administrator rights and is needed only for the Hyper-V backend or Windows containers.
On the configuration page, make sure Use WSL 2 instead of Hyper-V is selected (if the option is shown).
Complete the wizard and select Close.
You can also install from the command line, which is useful for scripted setups. From the folder containing the installer, run in PowerShell:
Start-Process "Docker Desktop Installer.exe" -Wait -ArgumentList "install", "--user", "--accept-license"
The --user flag selects per-user mode and --accept-license accepts the Docker Subscription Service Agreement in advance. Omit --user (and run as Administrator) for an all-users installation.
Step 3: Start Docker Desktop
Docker Desktop does not start automatically after installation. Search for Docker Desktop in the Start menu and open it. Accept the Docker Subscription Service Agreement when prompted; Docker Desktop will not run until the terms are accepted. Signing in to a Docker account is optional for personal use.
Wait until the Docker Desktop dashboard shows that the engine is running.
Step 4: Enable WSL Integration
Docker Desktop runs its own internal WSL distribution. To use the docker command from inside your Ubuntu distribution as well, enable integration:
Open Docker Desktop and go to Settings → Resources → WSL integration.
Turn on integration for your distribution (for example Ubuntu).
Select Apply (or Apply & restart).
Performance tip: Keep your project files inside the Linux file system (for example ~/projects in Ubuntu) rather than under /mnt/c/. Bind mounts and file watching are much faster when files live in the WSL file system.
Step 5: Verify the Installation
Open PowerShell and run:
docker version
docker run hello-world
Then open your Ubuntu terminal and run the same docker run hello-world command. If both show "Hello from Docker!", Docker works from Windows and from WSL.
Alternative: Docker Engine Directly Inside WSL (Without Docker Desktop)
Some developers, and organisations that do not want Docker Desktop, install Docker Engine directly inside their WSL Ubuntu distribution. This works because modern WSL supports systemd. Check that /etc/wsl.conf in Ubuntu contains:
[boot]
systemd=true
If you added it, run wsl --shutdown in PowerShell and reopen Ubuntu. Then follow Part 1 of this guide inside Ubuntu. You lose the Docker Desktop dashboard and its extra tools, and you should not run both setups at the same time, because two Docker engines competing for the same socket and ports causes confusing errors.
Part 3: Install Docker Desktop on macOS
Requirements
A Mac running one of the current or two previous major versions of macOS. When a new major macOS version is released, support for the oldest of the three is dropped.
At least 4 GB of RAM (8 GB or more is more comfortable for real projects).
The correct installer for your processor: Apple silicon (M-series) or Intel.
To check which processor you have, open Apple menu → About This Mac and look at the Chip (Apple silicon) or Processor (Intel) line. From Terminal, uname -m prints arm64 on Apple silicon and x8664 on Intel.
On Apple silicon, installing Rosetta 2 is recommended for the best experience. It is no longer strictly required, but a few optional command-line tools still need it:
softwareupdate --install-rosetta
Step 1: Download and Install
Quit tools that may call Docker in the background, such as VS Code and open terminals.
Download Docker Desktop for Mac for your chip from the official Docker website.
Open Docker.dmg and drag the Docker icon into the Applications folder.
Open Docker.app from Applications.
Accept the Docker Subscription Service Agreement. Docker Desktop will not run until you accept.
Docker Desktop then starts without further configuration. It installs its command-line tools in $HOME/.docker/bin and adds that folder to your PATH.
To install from the Terminal instead, run these commands from the folder where you downloaded the installer:
sudo hdiutil attach Docker.dmg
sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --accept-license
sudo hdiutil detach /Volumes/Docker
The install step can take several minutes the first time because macOS runs security checks on the application.
Step 2: Verify the Installation
Open a new Terminal window (so the updated PATH is loaded) and run:
docker version
docker run hello-world
Note: Current Docker Desktop releases for Mac do not create the default Docker socket at /var/run/docker.sock unless you enable it. If a third-party tool expects that socket, turn it on in Docker Desktop → Settings → Advanced.
Verify Your Docker Installation on Any Platform
Whichever platform you used, these commands confirm that every part of the installation works:
docker version
docker info
docker compose version
docker buildx version
docker run --rm hello-world
If docker version shows a Client section but an error instead of a Server section, the CLI is installed but cannot reach the Docker daemon. See the troubleshooting table below.
Common Installation Errors and How to Fix Them
Frequently Asked Questions
Is Docker free to install?
Docker Engine is free and open source on Linux. Docker Desktop is free for personal use, education, non-commercial open source and small businesses (fewer than 250 employees and less than USD 10 million in annual revenue). Larger organisations need a paid subscription for Docker Desktop.
Should I install docker.io from the Ubuntu repositories?
No. The docker.io package is maintained by Ubuntu rather than Docker and is usually older. Install docker-ce from Docker's official repository as shown in Part 1, and remove docker.io first if it is installed.
Can I install Docker on Windows 10 or 11 Home?
Yes. Docker Desktop with the WSL 2 backend runs on Home editions that meet the version requirements. Home editions run Linux containers only; Windows containers need Pro or Enterprise.
Do I need Docker Desktop to use Docker on Windows?
No. You can install Docker Engine directly inside a WSL 2 Linux distribution, as described in the alternative section of Part 2. Docker Desktop is simply the easiest and most integrated option.
How do I check which version of Docker is installed?
Run docker version. It shows the versions of both the Docker client and the Docker Engine server.
Is Docker Compose installed automatically?
Yes. Docker Desktop includes Docker Compose, and the Ubuntu instructions in this guide install the docker-compose-plugin package. Use it as docker compose (with a space); the old standalone docker-compose command is no longer the recommended tool.
Conclusion and Next Steps
You now have a working Docker installation that follows the official recommendations: Docker Engine from Docker's own repository on Ubuntu, or Docker Desktop with the right backend on Windows and macOS. You have also applied the post-install settings that prevent the most common problems later, namely non-root access, log rotation and an awareness of how published ports interact with your firewall.
Continue the Docker course with these tutorials on BitCodeMatrix:
What Is Docker? — the problems containers solve and where Docker fits
Docker Daemon Explained — what is actually running behind the docker command
Docker Containers Explained — how containers work under the hood
Docker Commands Cheat Sheet (next in the course) — managing the full container lifecycle from the command line