Skip to content
Runbook

Install Docker on macOS

Container engine to package, distribute, and run applications in isolation.

Containerscontainercontainerdevopscomposeoci

Installation

Docker Desktop (Homebrew Cask) · Homebrew
brew install --cask docker-desktop

Installs the Docker Desktop application. Launch it afterward (Applications or Spotlight) to start the engine.

Verify the installation

Verify
docker --version

Important files

TypePathDescription
config~/.docker/config.jsonDocker client configuration (registry authentication, aliases).
socket~/.docker/run/docker.sockDefault socket exposed by Docker Desktop for the local client (since version 4.13).

Command-line tools

  • dockerCommand-line client to manage images and containers.
  • docker composeMulti-container orchestration (built-in subcommand).

Uninstall

Uninstall
brew uninstall --cask docker-desktop

Good to know

  • The engine only runs while the Docker Desktop application is launched; there is no systemd service on macOS.
  • To start Docker Desktop without clicking: open -a Docker.

Installation on macOS

The Homebrew Cask docker-desktop (canonical token) installs Docker Desktop, which bundles the engine, the client, Compose, and a graphical interface. Note: brew install docker WITHOUT the --cask option installs the CLI only (formula), not the Docker Desktop application. After installing with brew, you must launch the application at least once: it starts a lightweight Linux virtual machine (via Apple's virtualization framework) in which the daemon runs. As long as the application is not launched, docker ps returns a connection error to the daemon.

Accept the system authorization requested on first launch: Docker Desktop needs a privileged component to manage the socket and networking.

Once the application is launched, verify that the engine responds. docker --version only prints the client version; to prove the daemon is actually working, run docker run --rm hello-world (without sudo). This command pulls a small image, starts a container, and removes it immediately.

Apple Silicon and architectures

On Apple Silicon Macs (M1/M2/M3…), containers run in arm64 by default. To run an amd64 (x86_64) image, use the platform option, for example docker run --platform linux/amd64 …. By default, this emulation relies on the QEMU software emulator. Rosetta is only used if you explicitly enable the corresponding option in Docker Desktop's settings; it is therefore not used automatically. Either way the emulation works but is slower; prefer multi-architecture images whenever possible.

Common pitfalls

Do not confuse the docker-desktop Cask (Docker Desktop) with the CLI formula. If you had installed the docker formula (client binary only, via brew install docker without --cask), it may conflict in the PATH. Check with which docker that the command really points to the Docker Desktop installation.