DevOps Tutorials, Guides & Best Practices

A docker: command not found error is a shell problem before it is a Docker problem. Your terminal cannot find the Docker CLI binary. That is different from Docker being installed but stopped, or from a container failing after Docker starts.

Quick takeaway: First prove whether the Docker CLI exists in your current shell. Then fix the right layer: install, PATH, Docker Desktop CLI links, WSL integration, or Compose v1 versus v2.

If Docker exists but the daemon is unreachable, use Cannot Connect to Docker Daemon instead. If Docker runs but an image pull fails, use Manifest Unknown. This page is only about the CLI or Compose command being missing.

Fast Diagnosis

Start with commands that answer one question: can this shell find the Docker CLI?

command -v docker
which docker
docker version
printf '%s
' "$PATH"Code language: Bash (bash)

Result	Meaning	Next move
command -v docker prints a path	The Docker CLI exists in this shell	Run docker version; if daemon fails, switch to the daemon guide
No output from command -v docker	The shell cannot find the CLI	Fix install, PATH, symlink, or shell environment
docker compose version works	Compose v2 plugin is available	Use docker compose, not legacy docker-compose
docker-compose fails but docker compose works	Script uses old Compose v1 command	Update scripts and docs to Compose v2 syntax

Do Not Mix Up These Docker Errors

Many fixes online jump between CLI, daemon, image, and container errors. Keep them separate or you will reinstall Docker when you only needed a PATH fix.

Error text	Layer	Best next guide
docker: command not found	Shell cannot find Docker CLI	This guide
zsh: command not found: docker	Shell or PATH issue	This guide
docker-compose: command not found	Legacy Compose binary missing	This guide, Compose section
Cannot connect to the Docker daemon	Docker CLI exists, daemon unreachable	Cannot Connect to Docker Daemon
manifest unknown	Registry or image reference problem	Manifest Unknown Docker Fixes

Fix on macOS with Docker Desktop

On macOS, the usual Docker install is Docker Desktop. Docker documents the current Desktop install path in its Mac install guide. If the Desktop app is installed but your shell cannot find docker, check whether the CLI link exists.

open -a Docker
command -v docker
ls -l /usr/local/bin/docker /opt/homebrew/bin/docker 2>/dev/null
printf '%s
' "$PATH"Code language: Bash (bash)

If Docker Desktop is not running, start it first. If the CLI link is missing, recreate it from Docker Desktop settings or reinstall Desktop. If you use Homebrew shell paths, make sure your terminal startup files load the right Homebrew path for Apple Silicon or Intel.

macOS symptom	Likely cause	Fix
Docker Desktop app exists, terminal says command not found	CLI symlink missing or PATH not loaded	Start Desktop, check CLI links, reload shell
Works in one terminal but not another	Different shell startup files	Compare $SHELL and $PATH
Works after reinstall only once	Shell path not persistent	Fix .zshrc or terminal profile, not just the app

Fix on Linux

On Linux, install Docker Engine from the package path for your distro, then verify the CLI. Docker keeps current distro instructions in the Engine install documentation.

# Debian or Ubuntu example after setting up Docker's repository
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

command -v docker
docker versionCode language: Bash (bash)

After the CLI exists, the next failure may be permissions or daemon access. Docker documents Linux group setup in Linux post-install steps. That is not the same as command not found, but it often appears immediately after a successful install.

# If docker exists but requires sudo, this is a permission setup issue
sudo usermod -aG docker "$USER"
newgrp docker

docker run hello-worldCode language: Bash (bash)

Security note: membership in the Docker group grants high privileges on the host. Use it deliberately on shared systems.

Fix in Windows and WSL

With Docker Desktop on Windows, the common problem is environment split: PowerShell sees Docker, but WSL does not, or the other way around. Docker documents WSL integration in its WSL documentation.

where.exe docker
docker version
wsl.exe -l -vCode language: PowerShell (powershell)

# inside WSL
command -v docker
docker version
printf '%s
' "$PATH"Code language: Bash (bash)

If Docker works in PowerShell but not WSL, enable integration for the target distro in Docker Desktop settings, restart the WSL distro, and test again inside the same distro where your project runs.

Fix docker-compose: command not found

Docker Compose is the most common trap because the command changed. Docker now ships Compose as a CLI plugin in many installs, documented under Docker Compose install. The modern command is docker compose with a space.

docker compose version
docker-compose version

# modern Compose v2 syntax
docker compose up -d
docker compose logs --tail 100 webCode language: Bash (bash)

Old habit	Modern default	What to change
docker-compose up	docker compose up	Update scripts, Makefiles, README snippets, and CI steps
Install standalone docker-compose	Install Docker Compose plugin	Prefer package/plugin path for new systems
Assume Compose is bundled everywhere	Verify with docker compose version	Check Desktop, package, or plugin install

If your app starts after the command is fixed, use Docker Compose Up for startup behavior and Docker Logs Command when you need to inspect output.

PATH Fixes That Are Safe to Try

Do not paste random PATH exports into every shell file. First find where Docker actually lives, then add the smallest persistent path change for your shell.

echo "$SHELL"
printf '%s
' "$PATH" | tr ':' '
'
ls -l /usr/bin/docker /usr/local/bin/docker /opt/homebrew/bin/docker 2>/dev/nullCode language: Bash (bash)

If a path exists but your shell does not include it, add it to the startup file your shell actually reads. For zsh, that is commonly ~/.zshrc. For bash, it may be ~/.bashrc or ~/.bash_profile depending on login mode.

# zsh example for Apple Silicon Homebrew tools
printf '
export PATH="/opt/homebrew/bin:$PATH"
' >> ~/.zshrc
exec zsh
command -v dockerCode language: Bash (bash)

When Reinstalling Is the Right Move

Reinstall only after the basic checks show the CLI files are missing or corrupted. Reinstalling before checking PATH can hide the real problem and make it return later.

• Reinstall if Docker Desktop is absent or damaged.
• Reinstall if package manager reports Docker CLI is not installed.
• Repair PATH if the binary exists but this shell cannot find it.
• Update scripts if only docker-compose fails but docker compose works.
• Switch to the daemon guide if docker version finds the CLI but cannot reach the server.

Source Checks

This draft is source-backed against Docker documentation for Docker Engine installation, Linux post-install setup, Docker CLI reference, Docker Compose installation, Docker Desktop on macOS, and Docker Desktop WSL integration.

Internal differentiation is based on existing RepoNotes pages for daemon startup, image pull errors, Compose startup, container commands, and logs: Cannot Connect to Docker Daemon, Manifest Unknown, Docker Compose Up, Run Commands Inside Docker Containers, and Docker Logs Command.

FAQ