Fix docker-compose: command not found on Linux

Seeing docker-compose: command not found is frustrating, especially when you have a deadline and your multi-container setup refuses to start. This error typically appears after a Docker Engine update, a fresh OS installation, or when cloning a repository with scripts that use the old hyphenated command. The fix depends on whether your Docker version includes the modern plugin or needs the standalone binary. This guide covers every recovery path, from the simple plugin migration to advanced troubleshooting for WSL2, PATH issues, and CI/CD environments.

Why This Error Happens

Docker Compose was originally a standalone Python binary called docker-compose (with a hyphen), maintained separately from Docker Engine. It had its own release cycle, occasionally caused version mismatch issues, and required manual updates. In 2023, Docker rewrote Compose in Go and integrated it as a native Docker CLI plugin called docker compose (with a space). The plugin ships with Docker Engine, updates automatically, and runs significantly faster — Docker’s own benchmarks show 2-3x faster startup on projects with many services compared to the legacy v1 Python version.

Most modern Docker installations include the plugin but not the standalone binary. When you type docker-compose, the shell cannot find it because the standalone binary was never installed or was removed during an upgrade. According to Docker’s official migration guide, the hyphenated docker-compose command is deprecated and will not receive further feature updates.

Quick Fix: Use the Plugin

The simplest fix requires no installation. Docker’s Compose plugin is likely already available under the new syntax:

docker compose version

Note the space instead of the hyphen. If this returns a version number, you are all set. Use docker compose going forward. All your existing docker-compose.yml files work identically — there is no syntax or feature difference between the old standalone and the new plugin for standard Compose functionality. The Docker Compose specification is identical regardless of which binary you use.

Updating Scripts and Aliases

Update any scripts, CI/CD pipelines, and documentation that use the hyphenated form:

# Instead of:
docker-compose up -d

# Use:
docker compose up -d

For a transitional period, create a shell alias:

alias docker-compose='docker compose'

Add this to your ~/.bashrc or ~/.zshrc. This workaround lets existing scripts run while you migrate them. However, be aware that aliases do not propagate into non-interactive shells — CI systems, cron jobs, and automated scripts need the actual command update.

Installing the Compose Plugin

If docker compose version also fails, the plugin is not installed. The Docker documentation recommends installing it through your system package manager for automatic updates:

# Ubuntu / Debian
sudo apt update && sudo apt install docker-compose-plugin

# Fedora / RHEL
sudo dnf install docker-compose-plugin

# Arch Linux
sudo pacman -S docker-compose

Manual Plugin Installation

For systems without apt or dnf, or for users who need the latest version immediately, install the plugin binary directly. This approach is documented in Docker’s Compose plugin installation guide:

mkdir -p ~/.docker/cli-plugins/
curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

Docker scans ~/.docker/cli-plugins/, /usr/local/lib/docker/cli-plugins/, and /usr/lib/docker/cli-plugins/ for plugins. Verify installation:

docker compose version
# Should show: Docker Compose version v2.27.0

Installing Standalone docker-compose (Legacy)

If your Docker version does not support plugins (Docker Engine < 20.10), you must install the standalone binary. Docker strongly recommends upgrading your Engine version, but the standalone binary remains available for legacy systems:

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Verify:

docker-compose --version

Note that the standalone v1 binary is no longer actively maintained and may contain unpatched security vulnerabilities. Docker has recommended migrating to the plugin version since Docker Engine 20.10, released in December 2020. If you are stuck on an older Engine version, prioritize an upgrade as part of your infrastructure maintenance cycle.

Common Troubleshooting Steps

Permission Denied

If the standalone binary gives a permission error after installation:

sudo chmod +x /usr/local/bin/docker-compose

The downloaded binary needs execute permissions. This is a common oversight when using curl to download files.

Command Not Found After Installation

Ensure the install directory is in your PATH:

echo $PATH | grep /usr/local/bin

If not present, add it to your shell configuration:

export PATH="/usr/local/bin:$PATH"

For permanent configuration, add this line to ~/.bashrc, ~/.zshrc, or ~/.profile:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

WSL2-Specific Issues

Windows users running Docker through WSL2 may encounter this error if Docker Desktop is not configured to use the WSL2 backend. Open Docker Desktop Settings → Resources → WSL Integration, ensure your WSL2 distro is enabled, then restart Docker Desktop and your WSL2 terminal. The Docker Desktop WSL2 backend provides native Linux performance while sharing the Docker daemon with Windows. Microsoft’s WSL2 documentation confirms that Docker Desktop’s WSL2 integration is the recommended setup for Windows Docker development.

Docker Desktop Version Compatibility

Docker Desktop 4.25+ ships with Compose v2 as the default. If you are running an older Docker Desktop version, update to the latest release to ensure Compose plugin availability. On macOS, check for updates via the Docker Desktop menu. On Windows, Docker Desktop checks automatically but you can trigger a manual check from the system tray menu. Older Docker Desktop versions may require the standalone binary as a fallback.

User Not in Docker Group

If docker commands require sudo but you want to run them as a non-root user:

sudo usermod -aG docker $USER

Log out and back in for group membership changes to take effect. This is unrelated to Compose but often surfaces simultaneously for new Docker setups. The Docker post-installation documentation covers this in detail.

Docker Compose Migration Checklist

Migrating from docker-compose (v1, Python) to docker compose (v2, Go plugin) requires careful attention to compatibility and workflow changes.

Compatibility Verification

1. Check Docker Engine version — must be 20.10 or newer for plugin support
2. Verify plugin availability — docker compose version should return v2.x.x
3. Test with existing compose files — run docker compose config to validate parsing
4. Review .env file handling — v2 reads .env files by default; ensure variables resolve correctly
5. Check volume and network names — v2 may use different naming conventions in some edge cases

Script and Pipeline Updates

# Find all occurrences of docker-compose in your codebase
grep -r "docker-compose" --include="*.sh" --include="*.yml" --include="*.yaml" .

# Test CI/CD pipeline locally with the new syntax
docker compose -f docker-compose.ci.yml up --abort-on-container-exit

Performance Expectations

Teams that migrate from v1 to v2 typically see:

• 2-3x faster startup for projects with 10+ services
• Reduced memory usage (Go binary vs Python interpreter)
• Better error messages with stack traces
• Native BuildKit integration for parallel builds

FAQ

Why did Docker switch from docker-compose to docker compose?

Docker rewrote Compose from Python to Go and integrated it as a CLI plugin for faster performance, unified release cycles with Docker Engine, and elimination of version mismatch issues. The plugin architecture also allows third-party tools to extend Docker’s CLI consistently. This migration is documented in Docker’s official Compose v2 announcement.

Can I keep using docker-compose with an alias?

Yes, alias docker-compose='docker compose' works perfectly as a transitional measure. However, update your scripts and CI pipelines to use the native command. Aliases do not propagate into non-interactive shells, so CI systems, cron jobs, and automated scripts need the actual command update.

Do I need both the standalone binary and the plugin?

No. Installing both is unnecessary and can cause confusion. If you have the plugin (Docker Engine 20.10+), use docker compose. Remove the standalone binary with sudo rm /usr/local/bin/docker-compose to avoid accidentally using the deprecated version.

How do I check which version of Compose I am running?

For the plugin: docker compose version. For the standalone binary: docker-compose --version. The plugin version string includes “Docker Compose version v2.x.x”, while the standalone shows “docker-compose version 1.x.x”.

What if my CI/CD system still uses docker-compose?

Update your CI configuration files to use docker compose instead. GitHub Actions, GitLab CI, and Jenkins all support the modern syntax. For legacy pipelines you cannot modify, install the plugin in your CI runner image or base Docker image rather than relying on the deprecated standalone binary.

Conclusion

The docker-compose: command not found error is a migration signal from the old standalone binary to Docker’s integrated plugin. The fix is typically straightforward: use docker compose (with a space), install the docker-compose-plugin package, or configure your WSL2 environment. Choose the plugin approach for long-term compatibility and migrate all scripts and CI pipelines to the new syntax. For more Docker troubleshooting, read our Docker logs and debugging guide or get started with the Docker beginner’s guide.

Troubleshooting Docker Compose Issues

The docker-compose: command not found error typically indicates Compose V1 is not installed. Modern Docker Desktop bundles Compose V2 as a Docker CLI plugin, invoked as docker compose (space, not hyphen). To install Compose V2 on Linux, download the binary from GitHub releases and place it at /usr/local/lib/docker/cli-plugins/docker-compose. Make it executable with chmod +x and verify with docker compose version. If docker-compose (V1) is required, install it via pip: pip install docker-compose — but V1 is deprecated and should be migrated. Common PATH issues: the Docker CLI plugin directory may not be in $PATH; Docker Engine looks in ~/.docker/cli-plugins/ and /usr/local/lib/docker/cli-plugins/. Check installed plugins with docker info | grep Plugins. Old scripts using docker-compose (with hyphen) will fail on systems with only V2. Create an alias or symlink: alias docker-compose=’docker compose’. For GitHub Actions, the docker/compose-switch tool forwards V1 commands to V2.

Version Compatibility and Migration

Compose file format versions v2 and v3 work with both Compose V1 and V2. However, V2 supports newer features like include, profiles, and watch that are not available in V1. Migrate from docker-compose.yml to compose.yaml (the preferred filename) and update CI scripts accordingly. Test your migration with docker compose config to validate the resolved configuration.