Installing Docker on macOS

macOS cannot run containers directly, they are a Linux kernel feature, so Docker Desktop runs a lightweight Linux VM and hands your docker commands to the engine inside it. The install itself is a drag-and-drop; the two things that will actually cost you time afterwards are CPU architecture and bind mount performance, both covered below.

Download the correct build for your chip. Apple Silicon and Intel are separate installers, and the wrong one either refuses to open or runs under emulation.

uname -m

arm64        # Apple Silicon (M1 and later)
x86_64       # Intel

Homebrew works too, and is easier to script:

brew install --cask docker

Prerequisites

Before installing Docker on macOS, ensure your system meets these requirements:

macOS Requirements

• macOS: Version 11 or newer
• Processor: Intel chip or Apple Silicon (M1/M2/M3)
• RAM: Minimum 4GB (8GB recommended)

Installing Docker Desktop on macOS

Docker Desktop for Mac provides a native application that runs seamlessly on both Intel and Apple Silicon Macs.

Step 1: Download Docker Desktop

1. Visit https://www.docker.com/products/docker-desktop
2. Select "Download for Mac"
3. Choose the version for your chip:
   • Apple Chip (M1/M2/M3)
   • Intel Chip

Step 2: Install Docker Desktop

1. Open the downloaded .dmg file
2. Drag the Docker icon to your Applications folder
3. Launch Docker from Applications
4. Grant necessary permissions when prompted

Step 3: Configure Docker Desktop

1. Click the Docker icon in the menu bar
2. Select "Preferences" or "Settings"
3. Adjust resources (CPU, Memory, Disk) based on your needs
4. Recommended settings:
   • CPUs: 4
   • Memory: 4GB minimum, 8GB recommended
   • Disk: 64GB

Step 4: Verify Installation

Open Terminal and run:

docker --version
docker run hello-world

Configuring Docker Desktop on macOS

Resources Allocation

Proper resource allocation ensures optimal performance:

CPU

• Development: 2-4 CPUs
• Production builds: 4-8 CPUs
• Apple Silicon: Can handle more due to efficiency

Memory

• Minimal: 2GB
• Development: 4-8GB
• Heavy workloads: 8-16GB

Disk

• Minimal: 32GB
• Recommended: 64GB or more

Docker Desktop Settings

Access settings through the Docker Desktop menu:

1. General

   • Start Docker Desktop when you log in
   • Use Virtualization framework (Apple Silicon)
   • Send usage statistics (optional)

2. Resources

   • Adjust CPU, Memory, Swap, and Disk limits
   • Configure file sharing directories

3. Docker Engine

   • Edit daemon.json for advanced configuration
   • Configure registry mirrors
   • Set insecure registries

4. Kubernetes (Optional)

   • Enable Kubernetes for local development
   • Useful for testing Kubernetes deployments

Troubleshooting macOS Installation

Permission Denied

Problem: "Cannot connect to Docker daemon"

Solution:

1. Ensure Docker Desktop is running
2. Check menu bar for Docker icon
3. Restart Docker Desktop
4. Check that Docker has necessary permissions in System Preferences > Security & Privacy

Docker Not Starting

Problem: Docker Desktop won't start

Solution:

1. Quit Docker Desktop completely
2. Remove Docker.app from Applications
3. Delete ~/Library/Group Containers/group.com.docker
4. Reinstall Docker Desktop

Slow Performance

Problem: Docker containers run slowly

Solution:

1. Allocate more resources in Docker settings
2. Use named volumes instead of bind mounts for better performance
3. Consider using VirtioFS for improved file sharing (experimental)

Cannot Pull Images

Problem: "Error response from daemon: Get https://registry-1.docker.io/v2/"

Solution:

1. Check internet connection
2. Verify firewall settings
3. Configure proxy if needed in Docker Desktop settings

Testing Your Installation

Let's verify everything works correctly:

1. Check Docker Version

docker --version
docker compose version

2. View System Information

docker info

This displays:

• Number of containers (running, paused, stopped)
• Number of images
• Storage driver information
• System resources

3. Run a Test Container

docker run -d -p 8080:80 nginx

Then visit http://localhost:8080 in your browser. You should see the Nginx welcome page!

4. List Running Containers

docker ps

5. Stop and Remove the Container

docker stop $(docker ps -q)
docker rm $(docker ps -aq)

macOS-Specific Features

Apple Silicon Optimization

Docker Desktop for Apple Silicon (M1/M2/M3) offers:

• Native performance: Runs natively on ARM architecture
• Rosetta 2 emulation: Can run x86_64 images when needed
• Better battery life: More efficient than Intel-based systems

File Sharing Performance

For best performance on macOS:

• Use named volumes for database storage
• Avoid mounting large directories from macOS filesystem
• Consider using Docker volumes for frequently accessed files

Virtualization Framework

On macOS 12.5+, Docker can use Apple's Virtualization framework for:

• Better performance
• Improved resource management
• Native integration with macOS

Docker Desktop Dashboard

The Docker Desktop dashboard on macOS provides:

• Visual interface to view running containers
• Manage images and volumes
• Monitor resource usage
• Access container logs
• Start/stop/restart containers with one click

Best Practices for macOS

1. Keep Docker Updated

Regularly update Docker Desktop to get the latest features and security patches:

• Check for updates in Docker Desktop preferences
• Enable automatic updates for convenience

2. Allocate Resources Wisely

Don't over-allocate resources:

• Monitor actual usage with docker stats
• Adjust based on your workload
• Leave resources for macOS and other applications

3. Use Official Images

Always start with official images from Docker Hub to ensure security and reliability.

4. Configure File Sharing

Only share directories that Docker needs to access:

• Reduces security risks
• Improves performance
• Minimizes permission issues

Apple Silicon: the architecture problem

The one thing that will genuinely catch you out. An M-series Mac builds arm64 images by default. Push one to a registry, deploy it to ordinary amd64 servers, and the container dies at startup:

exec /app/server: exec format error

Nothing is wrong with the image. It is compiled for the wrong CPU.

Check what you have built:

docker image inspect myapp:1.0 --format '{{.Architecture}}'

arm64

For a one-off, build for the target instead. This uses emulation, so it is noticeably slower:

docker build --platform linux/amd64 -t myapp:1.0 .

For anything shared, publish a multi-architecture image so every host pulls the variant it needs:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/acme/myapp:1.0 \
  --push .

--push is required for multi-platform builds: the local image store cannot hold a multi-arch manifest, so --load only works for a single platform.

The same mismatch runs the other way. An amd64-only third-party image runs under emulation on your Mac and may simply refuse:

no matching manifest for linux/arm64/v8 in the manifest list entries

Older database images are the usual offenders. --platform linux/amd64 on docker run gets you going, at a real performance cost.

Bind mount performance

The long-standing macOS complaint. Every file operation on a bind-mounted host directory crosses the VM boundary, and node_modules generates a great many of them.

Two settings in Docker Desktop are worth checking:

VirtioFS: Settings → General → Choose file sharing implementation. It is the default on current versions and substantially faster than the older gRPC-FUSE. If you have upgraded Docker Desktop over several years, you may still be on the old one.

Rosetta for x86/64 emulation: Settings → General, on Apple Silicon. Considerably faster than QEMU when you do need to run amd64 images.

Beyond that, keep dependency directories out of the mount so they live in the container's own filesystem:

services:
  api:
    volumes:
      - .:/app
      - /app/node_modules     # anonymous volume shadows the host directory

If you would rather not run Docker Desktop

Docker Desktop requires a paid subscription for commercial use in larger organisations. On macOS the common free replacement is Colima, a minimal Lima VM running Docker Engine:

brew install colima docker docker-compose
colima start --cpu 4 --memory 8
docker run --rm hello-world

It provides a normal Docker socket, so the CLI, Compose and Testcontainers work unchanged. Rancher Desktop and Podman Desktop are the other established options, and OrbStack is a commercial alternative known for being fast and light.

Where to go next

• Key Docker concepts: the object model in one page
• Docker images and containers
• Dockerfile basics: build your first image
• Docker volumes: and the bind mount performance trade

---

Key takeaways

• Download the installer matching your chip. uname -m tells you which.
• Apple Silicon builds arm64 by default, which produces exec format error on amd64 servers.
• Publish multi-arch images with buildx, and remember --push is mandatory for them.
• Enable VirtioFS, and Rosetta if you run amd64 images. Both make a measurable difference.
• Shadow node_modules with an anonymous volume so it lives in the VM, not across the boundary.
• Cap the VM's CPU and memory in Settings → Resources; the defaults suit neither light nor heavy use.
• Colima is the usual free replacement when Docker Desktop's licence does not fit.

---

Check your understanding

---

Frequently Asked Questions

Why does my Docker image built on an M1 or M2 Mac fail on the server?

Because Docker builds for the host architecture, and Apple Silicon is arm64 while most servers are amd64. The container starts and immediately exits with exec format error, which does not mention architecture at all. Check with docker image inspect <image> --format '{{.Architecture}}'. For images others will run, build multi-architecture: docker buildx build --platform linux/amd64,linux/arm64 -t <image> --push .. For a quick one-off, docker build --platform linux/amd64 works but runs under emulation and is slower.

Why are Docker volumes so slow on macOS?

Every file operation on a bind-mounted host directory has to cross the boundary into the Linux VM, and workloads like node_modules or a Rails app generate enormous numbers of small operations. Make sure VirtioFS is selected in Settings → General. It is the default now and much faster than the older gRPC-FUSE, but upgraded installations sometimes still use the old one. Then shadow dependency directories with an anonymous volume (- /app/node_modules in Compose) so they stay inside the VM's own filesystem.

Should I install Docker Desktop with Homebrew or the .dmg?

Either works and they install the same application. brew install --cask docker is easier to script and keeps Docker in the same update flow as your other tools, which is why it suits dotfiles and new-machine setups. The .dmg from Docker's site is more explicit about which build you are getting, which matters because Apple Silicon and Intel have separate downloads. Homebrew picks the right one for your machine automatically.

What is the free alternative to Docker Desktop on Mac?

Colima is the most common: brew install colima docker docker-compose then colima start. It runs Docker Engine inside a minimal Lima VM and exposes a standard Docker socket, so the CLI, Compose files and Testcontainers all work unchanged. Rancher Desktop and Podman Desktop are the other established open-source options, and OrbStack is a paid alternative noted for speed and low resource use. All of them exist largely because Docker Desktop requires a subscription for commercial use above roughly 250 employees or $10M revenue.

How much RAM should I give Docker Desktop on a Mac?

Start at about a quarter of your physical memory and adjust from what you actually see. On a 16 GB machine, 4 GB suits a couple of services and 8 GB is reasonable if you run a database and several containers at once. Watch real consumption with docker stats rather than guessing. Over-allocating is a genuine cost on macOS, because the VM holds that memory whether containers use it or not, and the system has less for everything else.

Why does "no matching manifest for linux/arm64" appear when pulling an image?

That image publishes no arm64 build, which is common for older or smaller third-party images, and databases in particular. Run it under emulation with docker run --platform linux/amd64 <image>, accepting that it will be slower. Check whether a newer tag is multi-arch first, docker manifest inspect <image> lists the platforms available, since most widely used images added arm64 support once Apple Silicon became common.