This guide covers one thing: installing Docker Desktop on macOS and verifying it runs.

No instructions for Windows, Ubuntu, or other Linux distros. Those platforms need different steps.

What is Docker Desktop?

Docker Desktop provides a GUI, Docker CLI, and Docker Engine so developers can work with containers on macOS.

Basic workflow:

Docker Architecture Flow

Terminal
↓		 → Docker CLI
↓		 → Docker Desktop
↓		 → Image & Container

Image: Package containing everything needed to run an application

Container: Running instance created from an image

When you run an image that doesn’t exist locally, Docker pulls it from the registry, creates a container, then executes the command declared in the image.

Prerequisites

Your Mac must meet these requirements:

ComponentRequirement
macOSSupported version (latest recommended)
RAM8 GB minimum (recommended)
CPUApple Silicon (M1/M2/M3/M4) or Intel
DiskEnough space for images, containers, volumes
InternetRequired for downloading Docker images
Unlike Windows, macOS does not need WSL or BIOS virtualization setup. Docker Desktop runs through Apple's Virtualization framework.

Check macOS Version

Open Terminal and run:

sw_vers

Expected output:

ProductName:    macOS
ProductVersion: 15.6
BuildVersion:   24G84

You can also check via Apple Menu () → About This Mac.

Build numbers vary per Mac. What matters is that macOS is still within its support window so Docker Desktop will run.

Check CPU Architecture

Docker Desktop ships two different builds: Apple Silicon and Intel. Pick the right installer.

uname -m

Result:

OutputArchitecture
arm64Apple Silicon (M1/M2/M3/M4)
x86_64Intel

Download and Install Docker Desktop

  1. Download the installer from the official site: Docker Desktop for Mac
  2. Open the downloaded .dmg file
  3. Drag Docker.app into the Applications folder
  4. Launch Docker Desktop from Applications
  5. Approve the system prompt for privileged actions if macOS asks

Start Docker Desktop & Verify Status

Open Docker Desktop from Applications.

Wait until the whale icon in the top menu bar stops animating.

The status should show:

Engine running

Do not continue until Docker Engine has finished starting.

Verify Docker CLI

Open a new Terminal window and check the Docker CLI version:

docker --version

This only confirms the Docker CLI is installed. Continue to check connection to Docker Engine:

docker version

Success must show both Client and Server sections:

Client:
 Version:           ...

Server: Docker Desktop
Engine:
Version:          …

If only the Client section appears, the CLI is installed but can’t connect to the Docker Engine.

Verify Docker Engine & Run Test Container

Check Engine info:

docker info

Run a test container:

docker run --rm hello-world

Success output contains:

Hello from Docker!

If you see this message, Docker CLI connected to Docker Engine, the image was pulled, and the container ran successfully.

Basic Verification Commands

# List downloaded images
docker image ls

# List running containers
docker container ls


# List all containers (including stopped)
docker container ls —all


# Check Docker disk usage
docker system df

Note: Don't run docker system prune --all unless you understand what data will be deleted.

Troubleshooting Common Issues

Step 1 — Docker Error?

Step 2 — Is Docker Engine running?

Status Action
Not Running → Follow Path A below
Running → Follow Path B below

Path A — Docker Engine Not Running

Step 1: Quit Docker Desktop completely (right-click the whale icon → Quit Docker Desktop)

Step 2: Reopen Docker Desktop from Applications

Step 3: Wait 1–2 minutes for Engine to initialize

docker info # confirm Engine status

Go back to Step 2 — Is Engine running now?

Yes → Docker works!
No → Restart your Mac, then go back to Step 2

Path B — Engine Running But Still Failing

Engine running? → Continue troubleshooting

Can't Pull Images?

Yes

Open Docker Desktop → Settings → Resources → Proxies

Check if VPN/Proxy is interfering

Proxy disabled?

  • → Yes: Docker works!
  • → No: Disable VPN/Proxy and retry
No Docker works!

Fix 1 — “App is damaged” or “Cannot open because developer cannot be verified”

  • Open System Settings → Privacy & Security
  • Scroll down and click Open Anyway next to the Docker Desktop message
  • Reopen Docker Desktop from Applications

Fix 2 — Apple Silicon vs Intel mismatch

  • Re-check uname -m
  • Remove the wrong build, then download the matching installer from the official download page

After Completion

Docker Desktop is ready when all three checks pass:

docker --version           # Verify CLI installed
docker version             # Verify CLI connects to Engine
docker run --rm hello-world  # Verify container runs

Source Code

Source and test scripts in repo: github.com/levantri10/kizetech_blog

References