Docker Command Not Found on Mac

Problem Statement

When attempting to run Docker commands on macOS, users frequently encounter the error:

sudo: docker: command not found

This occurs even after installing Docker Desktop through official installers or package managers like Homebrew. The core issue is that Docker's command-line tools are not properly accessible in your system's PATH environment variable.

Solution Overview

There are several approaches to resolve this issue, depending on your Docker Desktop version and configuration:

1. PATH configuration - Add Docker binaries to your shell's PATH
2. Docker Desktop settings - Change CLI tool installation location
3. Manual repair - Fix broken installations or symlinks

Docker CLI Location Changes

Recent versions of Docker Desktop (4.18+) changed the default installation location from /usr/local/bin to $HOME/.docker/bin, requiring manual PATH configuration.

Detailed Solutions

Method 1: Update Your Shell Configuration (Recommended)

Add the appropriate path to your shell configuration file based on your Docker Desktop settings:

ZSH - ~/.zshrc

# For newer installations (Docker 4.18+)
export PATH="$PATH:$HOME/.docker/bin"

# For older installations
export PATH="$PATH:/Applications/Docker.app/Contents/Resources/bin/"

Bash - ~/.bash_profile

# For newer installations (Docker 4.18+)
export PATH="$PATH:$HOME/.docker/bin"

# For older installations
export PATH="$PATH:/Applications/Docker.app/Contents/Resources/bin/"

After editing your configuration file, reload it with:

ZSH

source ~/.zshrc

Bash

source ~/.bash_profile

Method 2: Configure Docker Desktop Settings

1. Open Docker Desktop
2. Go to Settings → Advanced
3. Under "Choose how to configure the installation of Docker's CLI tools":
   • Select System to install tools to /usr/local/bin (in system PATH)
   • Or select User to install to $HOME/.docker/bin (requires PATH update)
4. Click Apply & Restart

TIP

If Docker is already set to "System" but not working, try switching to "User" and back to "System" to trigger a reinstallation of CLI tools.

Method 3: Create an Alias

For a quick fix without modifying PATH, add an alias to your shell configuration:

alias docker="/Applications/Docker.app/Contents/Resources/bin/docker"

Method 4: System-wide PATH Configuration

For a system-wide solution that works across all shells:

1. Create a new file in /etc/paths.d/:

   sudo nano /etc/paths.d/docker

2. Add the path to Docker binaries:

   /Applications/Docker.app/Contents/Resources/bin

3. Save and open a new terminal session

Method 5: Repair Docker Installation

If CLI tools are missing or corrupted:

1. Open Docker Desktop
2. Check for repair notifications (often appears as a "Repair" button)
3. Alternatively, manually remove and recreate symlinks:

   rm -rf ~/Library/Containers/com.docker.*
   cd /usr/local/bin
   chmod 0755 dock*

4. Quit and restart Docker Desktop

Verification

After applying any solution, verify Docker is accessible:

docker --version
docker ps

Special Cases

For Rancher Desktop Users

If using Rancher Desktop instead of Docker Desktop, add this to your .zshrc:

export PATH="$HOME/.rd/bin:$PATH"

Homebrew Installation Issues

WARNING

Homebrew's Docker package (brew install docker) only installs the Docker client, not the complete Docker Desktop environment. For full functionality, download Docker Desktop directly from docker.com.

If you installed via Homebrew, ensure Docker Desktop is running from your Applications folder.

Persistent Solutions

To ensure Docker remains available after system restarts:

• Use Method 1 (PATH configuration) for persistent access
• Avoid temporary exports that only work in the current session
• Check that Docker Desktop is set to launch at login (in Applications → Docker → Preferences)

Conclusion

The "docker: command not found" error on macOS typically results from Docker CLI tools not being in your PATH. The optimal solution depends on your Docker Desktop version and installation method. For most users, updating the shell configuration file (Method 1) or adjusting Docker Desktop settings (Method 2) provides a permanent fix.

For the latest Docker Desktop versions (4.18+), remember that the default installation location has changed to $HOME/.docker/bin, requiring manual PATH configuration unless you select the "System" installation option.