Beginner guide

How to install Docker

No complicated theory. Install it in a few minutes and immediately check that it works.

10 minutes · Windows, macOS, and Linux

First, the short version

What is Docker?

Docker is a tool for running applications in separate containers. This means you do not need to install every PHP version, database, or other tool directly on your computer.

Think of it as a prepared box for an application. You open a project, run a few commands, and everyone on the team has the same environment.

Get ready

What you need

Nothing unusual. Just a few everyday things.

A computer with Windows 10 or 11, macOS, or a common Linux distribution.
A stable internet connection. The installer and first test download a few files.
Access to an account that can install programs. The installer may ask for an administrator password.
Windows needs WSL 2. If you do not have it yet, the installer or command below will guide you through it.

Step 1

Install Docker

Docker Desktop is the easiest start on Windows and macOS. On Linux, Docker Engine for your specific distribution is often the more practical choice.

Windows

Open the official installation link below and download Docker Desktop for Windows.
Run the installer. Keep the WSL 2 backend selected unless you have a reason to choose something else.
If it reports that WSL is missing, open Terminal or PowerShell as administrator, run the command below, and restart the computer.
After the restart, open Docker Desktop and wait until it finishes starting.

wsl --install

Official Windows guide

macOS

On the official page, choose the installer for Apple chip or Intel. You can find the chip type in Apple menu → About This Mac.
Open the downloaded file and move Docker to Applications.
Launch Docker from Applications. Confirm the requested permissions on first start.

Official macOS guide

Linux

Open the official guide for your distribution, such as Ubuntu, Debian, or Fedora.
Follow the commands for Docker Engine. Do not copy random install scripts from forum posts.
If Docker Engine is already installed, do not add Docker Desktop only because it looks convenient. On Linux they can run alongside each other and create avoidable conflicts.

Official Linux guide

Step 2

Check that Docker is running

Open a new Terminal, PowerShell, or command prompt. Then try these commands.

Check the version

If you see a version number, the Docker command is available.
```
docker --version
```
Run the first test

Docker downloads a small test image and prints a welcome message. That is exactly the result you want.
```
docker run hello-world
```
Optionally check Compose

You will use it later to run several parts of a project at once. Docker Desktop includes it out of the box.
```
docker compose version
```

If something goes wrong

Common problems

“docker” is not recognized as a command

Close the Terminal and open a new one. If the error remains, Docker probably did not finish installing or Docker Desktop is not running yet.

Docker Desktop does not start on Windows

Finish setting up WSL 2 and restart the computer. If the problem remains, check that virtualization is enabled in your computer firmware. Then open Troubleshoot in Docker Desktop and view the diagnostics.

wsl --status

Linux reports “permission denied”

Do not automatically run everything through sudo. Complete the official post-install steps for your user, then sign out and back in. The docker group grants powerful permissions, so add only your own trusted account to it.

You later run into a port already in use

See which containers are running. Then stop the one you no longer need or change the project to use a different port.

docker ps

Done

Docker is ready.

Docker is now running. When you open a project with compose.yaml, you will most often start with docker compose up.

Read Docker in the glossary All guides