How to Fix 'docker-compose: command not found' Error

In this tutorial, you'll learn about How to Fix 'docker. We cover key concepts, practical examples, and best practices.

The Problem

You type docker-compose up and get:

docker-compose: command not found

This happens when Docker Compose is not installed or not in your PATH. Modern Docker installations include <a href="/devops/docker-compose/">docker compose</a> as a plugin, but the standalone docker-compose binary may be missing.

Quick Fix

Step 1: Try the plugin syntax first

Docker Compose is now a built-in Docker plugin. Use the subcommand syntax:

docker compose up -d

If this works, you don't need the standalone binary. The plugin provides the same functionality with a dash instead of a hyphen.

Step 2: Install Docker Compose standalone

If <a href="/devops/docker-compose/">docker compose</a> also fails, install the standalone binary:

# Download the latest release
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Apply executable permissions
sudo chmod +x /usr/local/bin/docker-compose

# Verify
docker-compose --version

Expected output:

Docker Compose version v2.30.1

Step 3: Install via apt (Ubuntu/Debian)

sudo apt update
sudo apt install docker-compose-plugin

Verify:

docker compose version

Alternative Solutions

If the above fails, use pip to install Docker Compose:

pip3 install docker-compose

This installs an older v1 version but works on systems where the binary is incompatible.

Inspect Container Configuration

docker inspect <container-id> --format '{{json .Config}}' | python3 -m json.tool
# {
#   "Hostname": "abc123",
#   "Env": ["PATH=/usr/local/bin:..."],
#   "Cmd": ["node", "app.js"]
# }

Use docker inspect to examine the full configuration of a container. This reveals misconfigurations in environment variables, command arguments, and network settings that may not appear in logs.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Install docker-compose-plugin via your package manager to keep it updated.
• Use <a href="/devops/docker-compose/">docker compose</a> (subcommand) instead of docker-compose (standalone) in scripts.
• Add /usr/local/bin to your PATH if it isn't already.