Install Docker Desktop

You've read about containers and even played with docker run in a sandbox, but you can't ship a single image until you have Docker running on your own machine. This lesson walks you through installing Docker Desktop on macOS — the official, all-in-one solution that gives you the Docker engine, CLI, and a clean UI. By the end you'll have a working local environment and the confidence to start building real containers.

The problem this lesson solves

Without a local Docker installation you are limited to cloud playgrounds or CI pipelines that hide the messy details. Every time you run docker build on a new Mac you face the same friction:

• Missing engine — the docker command fails with command not found.
• Mismatched versions — the Docker CLI you have doesn't match the engine your team uses.
• Resource starvation — running containers on a laptop that's already juggling Chrome, Slack, and a dozen terminal tabs.

Docker Desktop for Mac solves all three. It bundles the latest stable engine, a CLI that auto-updates, and a Kubernetes cluster that runs natively on macOS. Installing it once means you never think about “how do I get Docker?” again.

Core concept / mental model

Think of Docker Desktop as the operating system for containers on your Mac. Just as macOS provides a kernel, file system, and window manager, Docker Desktop provides:

• dockerd — the daemon that manages containers, images, networks, and volumes.
• docker CLI — the command-line tool you type into the terminal.
• Hypervisor.framework — Apple’s native virtualization layer, so containers run at near-native speed.
• Docker Dashboard — a GUI that shows running containers, resource usage, and logs in real time.

Important distinction: Docker Desktop is not running Linux containers directly on macOS. It runs a lightweight Linux virtual machine (VM) inside the Hypervisor.framework. The Docker CLI talks to the daemon inside that VM. This means your containers think they are on Linux — and that’s exactly the point.

┌──────────────────────────────┐
│         macOS                │
│  ┌──────────────────────┐   │
│  │  Docker Desktop      │   │
│  │  ┌────────────────┐  │   │
│  │  │ Linux VM       │  │   │
│  │  │  ┌──────────┐  │  │   │
│  │  │  │ dockerd  │  │  │   │
│  │  │  │  (engine) │  │  │   │
│  │  │  └──────────┘  │  │   │
│  │  └────────────────┘  │   │
│  └──────────────────────┘   │
└──────────────────────────────┘

How it works step by step

1. Pre-flight check

Before you download anything, confirm your Mac meets these requirements:

• macOS version 11 (Big Sur) or newer (Apple Silicon or Intel)
• At least 4 GB of RAM (8 GB+ recommended)
• At least 4 GB of free disk space

Pro tip: On Apple Silicon (M1/M2/M3) machines, Docker Desktop runs emulated Intel containers via Rosetta 2. This works fine for most images, but for best performance you should pull arm64-compatible images when available.

2. Choose your download

1. Go to the Docker Desktop download page.
2. Select Mac with Apple Chip or Mac with Intel Chip — pick the one that matches your hardware.
3. The .dmg file downloads. Size is roughly 700 MB.

3. Install Docker Desktop

1. Double-click the downloaded .dmg file. A Finder window opens.
2. Drag the Docker.app icon into the Applications folder.
3. Eject the .dmg volume (optional, but tidy).
4. Launch Docker Desktop from Applications or via Spotlight (Cmd+Space, type “Docker”).

4. Accept the license & grant permissions

• On first launch, you’ll see the Docker Software End User License Agreement. Read it, click Accept.
• macOS will ask for permission to install a networking helper. This is required for port forwarding. Click Allow.
• If you’re on Apple Silicon, you may get a prompt to allow the “Docker” kernel extension. Allow it.

5. Wait for the engine to start

The Docker whale icon appears in your menu bar. It will spin while the Linux VM boots. Once the icon becomes static (no animation), Docker is ready.

6. Verify the installation

Open Terminal and run:

docker version

Expected output (abbreviated example):

Client:
 Cloud integration: v1.0.35
 Version:           25.0.3
 API version:       1.44
 Go version:        go1.21.6
 Git commit:        4debf41
 Built:            Tue Feb  6 21:13:34 2024
 OS/Arch:          darwin/arm64

Server:
 Engine:
  Version:          25.0.3
  API version:      1.44 (minimum version 1.24)
  Go version:       go1.21.6
  Git commit:       f417435
  Built:            Tue Feb  6 21:13:34 2024
  OS/Arch:          linux/arm64
  Experimental:     false

Both Client and Server blocks must appear. If you see only Client, the daemon is not running — head to Troubleshooting below.

Hands-on walkthrough

Now you have Docker Desktop running locally. Let’s test it with a real container.

Example 1: Hello World

docker run hello-world

Expected output:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

Example 2: Run an interactive Ubuntu container

docker run -it --rm ubuntu bash

This downloads the official Ubuntu image, starts a container, drops you into a bash shell inside it. Run cat /etc/os-release to confirm you're on Linux. Type exit or press Ctrl+D to leave — the --rm flag deletes the container automatically.

Example 3: A simple web server

docker run -d -p 8080:80 nginx

The -d flag runs the container in the background (detached). -p 8080:80 maps your Mac’s port 8080 to the container’s port 80. Open a browser and visit http://localhost:8080 — you should see the default Nginx welcome page.

Example 4: List running containers

docker ps

Output shows your Nginx container:

CONTAINER ID   IMAGE   COMMAND                   CREATED         STATUS         PORTS                  NAMES
a1b2c3d4e5f6   nginx   "/docker-entrypoint.…"   5 seconds ago   Up 4 seconds   0.0.0.0:8080->80/tcp   beautiful_gould

Stop it with docker stop a1b2c3d4e5f6 (use the actual container ID).

Compare options / when to choose what

When to choose Docker Desktop: You want everything in one package, a visual dashboard, and the simplest onboarding.

When to choose CLI-only: You run Docker on a headless CI server or install via Homebrew for a minimal footprint.

When to choose a Linux VM (e.g., Multipass): You need fine‑grained control over kernel parameters or need to simulate a production Linux environment closely.

Troubleshooting & edge cases

Common errors

1. docker: command not found — Docker Desktop is not in your PATH. Reinstall from the .dmg, and make sure /Applications/Docker.app/Contents/Resources/bin is added to your shell’s PATH. Restart Terminal.

2. Cannot connect to the Docker daemon — The Linux VM failed to start. Check the Docker Dashboard: click the whale icon → Troubleshoot. Common cause: not enough disk space (free up 4+ GB) or a conflicting hypervisor (disable other VM apps like VMWare Fusion temporarily).

3. bash: docker: Operation not permitted on Apple Silicon — Rosetta 2 is missing. Run softwareupdate --install-rosetta in Terminal. Restart Docker Desktop.

4. Container exits immediately without error — You probably used docker run without -it or the entrypoint expects interaction. Use docker run -it IMAGE /bin/bash to debug.

5. Ports not accessible — another service is using port 8080. Change the mapping: -p 8081:80. Or stop the conflicting process: sudo lsof -i :8080.

Edge Cases

• Corporate proxy: Set HTTP_PROXY and HTTPS_PROXY in Docker Desktop → Settings → Resources → Proxies.
• File sharing performance: Code mounted into containers via -v is slower on macOS than on native Linux. For heavy I/O, copy files into the container instead of bind-mounting.
• Multiple Docker contexts: If you use multiple environments (e.g., Docker Desktop plus a remote Engine), run docker context ls and docker context use default to switch back.

What you learned & what's next

You now know:

• How to check system prerequisites for Docker Desktop on macOS
• The mental model of Docker Desktop as a Linux VM wrapping the Docker engine
• The complete installation flow: download, install, launch, and verify
• Four hands-on commands to test your setup (hello-world, ubuntu, nginx, ps)
• How Docker Desktop compares to CLI-only alternatives
• How to fix the five most common installation issues

Next lesson: [Create a Dockerfile] — you'll write a Dockerfile that builds a custom image from scratch. Without a working Docker Desktop, the docker build command is just a dream. But now you have your engine running. Let's build something.