Fix Docker Suddenly Not Working on Mac

Published: August 26, 2025  |  Categories: Docker, Mac, Troubleshooting

Warning: Some steps below will delete all your Docker containers and their data. Back up anything important before proceeding.

Docker Desktop on macOS can suddenly stop launching, freeze on startup, or become completely unresponsive — often after an OS update, a system crash, or a period of heavy use. This guide covers the most common causes and walks through a systematic fix from least destructive to most destructive.

How Docker Works on Mac (Background)

Unlike Linux, macOS doesn't have a native Linux kernel. Docker Desktop on Mac runs a lightweight Linux virtual machine (VM) under the hood using Apple's Hypervisor framework. All your containers run inside that VM.

This architecture means there are more moving parts that can break:

• The VM itself might fail to start
• The socket Docker clients talk to might not be created
• File-sharing mounts between macOS and the VM might go stale
• The Docker daemon inside the VM might crash

Understanding this helps you diagnose which layer is broken.

Prerequisites

• macOS with Docker Desktop installed
• Terminal access
• Admin (sudo) privileges

Quick Checks First

Before doing anything destructive, try these fast checks:

Check if Docker daemon is actually running:

docker info

If you get Cannot connect to the Docker daemon — the daemon isn't running. If you get output, Docker is alive and the issue is elsewhere.

Check Docker Desktop logs:

tail -100 ~/Library/Containers/com.docker.docker/Data/log/vm/dockerd.log

Look for obvious error messages. This often tells you exactly what's wrong.

Check available disk space:

df -h ~

Docker's VM needs free space to operate. Less than 2 GB free can cause startup failures.

Step 1: Force Quit Docker

If Docker Desktop is frozen and won't quit normally:

1. Open Activity Monitor (Applications > Utilities > Activity Monitor)
2. Search for Docker
3. Select Docker Desktop and click the Force Quit (X) button

Alternatively, from the terminal:

pkill -f Docker

Wait 5–10 seconds after killing it before trying to relaunch.

Step 2: Restart Docker Normally First

Before wiping anything, try a clean restart:

open -a Docker

Wait up to 2 minutes. If the whale icon in the menu bar stops animating and turns solid, Docker started successfully. Run docker ps to confirm. If it's still stuck after 2 minutes, proceed to the next steps.

Step 3: Remove Docker Container Files

This removes corrupted container data and resets Docker's internal state.

sudo rm -rf ~/Library/Containers/com.docker.*

What this does: Deletes all Docker container storage under your user library. This is irreversible — all stopped and running containers, their volumes, and their internal state will be gone after this step.

Step 4: Clear File Sharing Directories in Docker Settings

Docker's settings file sometimes references directories that no longer exist. This causes the VM to hang during startup as it tries to mount unavailable paths.

Open the settings file:

sudo nano ~/Library/Group\ Containers/group.com.docker/settings.json

Find the "filesharingDirectories" key and clear its array:

"filesharingDirectories": []

Save the file (Ctrl+O, then Enter) and exit (Ctrl+X). You can re-add your desired shared directories from Docker Desktop's Settings > Resources > File Sharing after it starts.

Step 5: Restart Docker and Verify

Launch Docker Desktop from your Applications folder. The first startup after a reset can take 60–90 seconds. Once Docker is running, verify it works:

docker run hello-world

You should see a "Hello from Docker!" message confirming everything is working.

Step 6: Full Uninstall and Reinstall (Last Resort)

If Docker still won't start, do a complete clean uninstall. If Docker Desktop won't open at all, remove it manually:

# Remove the app
sudo rm -rf /Applications/Docker.app

# Remove all data and config
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker
sudo rm -f /usr/local/bin/docker
sudo rm -f /usr/local/bin/docker-compose

Then download and reinstall the latest Docker Desktop from docker.com.

Why Does This Happen?

Common Error Messages and What They Mean

dial unix docker.raw.sock: connect: no such file or directory
→ Docker daemon is not running. Restart Docker Desktop.

Error response from daemon: OCI runtime create failed
→ Usually a permissions or disk space issue. Check df -h.

docker: command not found
→ Docker CLI is not in your PATH after reinstall. Restart your terminal or run export PATH=$PATH:/usr/local/bin.

Alternative: Use Colima Instead

If Docker Desktop keeps giving you trouble on Mac, consider Colima — a lightweight, open-source container runtime for macOS. It uses the same Docker CLI but without Docker Desktop's overhead:

brew install colima docker
colima start
docker run hello-world

Colima is free, uses less RAM, and starts faster than Docker Desktop for most development workflows.

References

• Docker Desktop Mac Troubleshooting Guide
• Colima — Container runtimes on macOS