Install Docker CLI on Mac with Colima — Fast Guide 2026

1. Why Docker Desktop Often Fails or Is Unsuitable

Docker Desktop on macOS is a GUI application that bundles:

• Docker daemon
• Docker CLI
• Docker Compose
• Credential helpers
• GUI system tray and settings

Issues we encountered:

• Homebrew installation repeatedly failed because of a conflicting binary (/usr/local/bin/hub-tool) pointing to a missing /Applications/Docker.app.
• Docker Desktop requires a large macOS GUI app that some developers may not want.
• GUI apps consume more system resources and don’t integrate well in a pure CLI workflow.
• CLI-only workflows with Docker Desktop require workarounds for credential helpers and build tools.

Conclusion: For pure command-line workflows, a lightweight Linux VM running Docker/Containerd is better.

2. Use Colima for a CLI-Only Docker Environment

Colima creates a lightweight Linux VM on macOS and runs a Docker-compatible runtime inside. It fully supports the Docker CLI and Compose.

Benefits:

• CLI-only, no GUI
• Small disk and memory footprint
• Fully compatible with docker and docker-compose
• Works with Apple Silicon and Intel Macs

3. Install Required Tools

Step 1: Install Homebrew (if not installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Colima

brew install colima

Step 3: Install Docker CLI and Compose

brew install docker docker-compose docker-buildx

• docker → CLI
• docker-compose → standalone Compose
• docker-buildx → build plugin for advanced builds

Note: Do not try to install Docker Desktop via Homebrew cask — it will fail if previous binaries exist or /Applications/Docker.app is missing.

Step 4: Start Colima

colima start

• Colima creates a Linux VM and runs a Docker daemon inside.
• After starting, you can use Docker CLI commands normally.

4. Handling Credential Helper Issues

In CLI-only mode, the macOS credential helper (docker-credential-osxkeychain) is not available. To fix:

1. Edit Docker config:

nano ~/.docker/config.json

2. Remove or comment out:

"credsStore": "osxkeychain"

3. Save the file. Docker CLI will now pull/push images without the credential helper.

5. Running Docker Compose Projects

Assuming you have a Compose file (e.g., compose.dev.yml) in your project:

docker-compose -f compose.dev.yml up -d

• -f compose.dev.yml points to your Compose file
• up -d runs containers in detached mode

Check running containers:

docker-compose ps

Follow logs:

docker-compose logs -f

Stop containers:

docker-compose down

Tip: Alias for convenience

To unify commands with the modern CLI:

alias docker-compose='docker compose'

Then you can run your usual docker-compose commands and they will invoke the CLI-compatible version automatically.

6. Cleaning Up Disk Space

Stopped containers, old images, volumes, and build cache can fill your disk. Recommended commands:

• Remove stopped containers:

docker container prune -f

• Remove unused images:

docker image prune -a -f

• Remove volumes:

docker volume prune -f

• Remove build cache:

docker builder prune -a -f

• One-shot cleanup:

docker system prune -a --volumes -f

7. Summary of Steps

1. Remove broken Docker Desktop remnants.
2. Install Colima via Homebrew.
3. Install Docker CLI, Compose, and Buildx.
4. Start Colima (colima start) to create a Linux VM with Docker daemon.
5. Fix docker-credential-osxkeychain issue by editing ~/.docker/config.json.
6. Use docker-compose -f compose.dev.yml up -d to run projects.
7. Clean up old containers, images, volumes, and build cache as needed.

8. Why This Setup Is Better

• Works entirely in the terminal.
• Lightweight and faster than Docker Desktop.
• No GUI app conflicts.
• Fully supports Docker CLI, Compose, Buildx, and Colima VM networking.
• Easier to automate for scripts, CI/CD, and development workflows.