Docker Compose vs docker-compose: Understanding the Difference and Migration

Problem Statement

Many Docker users have encountered two seemingly identical commands: docker-compose (with a hyphen) and docker compose (with a space). This can cause confusion when scripts work differently between systems or when documentation appears inconsistent.

The core issue is a significant transition in Docker's tooling architecture that occurred in recent years, moving from a standalone Python-based tool to a native Go-based CLI plugin integrated directly with Docker Engine.

Solution Overview

The Evolution of Docker Compose

Docker Compose has undergone two major versions:

• docker-compose (v1): The original Python-based standalone tool
• docker compose (v2): The newer Go-based Docker CLI plugin

Historical Context

The original tool was called fig before being renamed to docker-compose. The configuration file evolved from fig.yml to compose.yml to docker-compose.yml, and back to compose.yml as the preferred name in v2.

Key Differences

Aspect	docker-compose (v1)	docker compose (v2)
Implementation	Python	Go
Integration	Standalone binary	Docker CLI plugin
Default config file	docker-compose.yml	compose.yml
Project naming	Underscore separator (myproject_service)	Hyphen separator (myproject-service)
Development status	Deprecated	Actively maintained

Installation Methods

Installing docker compose (v2) on Linux

Manual Installation

mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

Package Manager

# Ubuntu/Debian
sudo apt-get install docker-compose-plugin

# Verify installation
docker compose version

Maintaining docker-compose (v1) Legacy Support

If you need to maintain backward compatibility with existing scripts:

# Install legacy docker-compose v1
VERSION=v2.12.2
sudo curl -SL https://github.com/docker/compose/releases/download/$VERSION/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
sudo chmod a+x /usr/local/bin/docker-compose

Important Behavioral Differences

Environment File Handling

One significant behavioral change affects how .env files are located:

Path Resolution Change

docker-compose reads the .env file from the current working directory, while docker compose reads it from the directory containing the Compose file. This can break setups where Compose files and environment files are in different directories.

Before (v1 behavior):

services:
  web:
    image: nginx
    env_file:
      - ${PWD}/.env  # Relative to current directory

After (v2 compatible):

services:
  web:
    image: nginx
    env_file:
      - ./.env  # Explicit relative path

Project Naming Convention

The automatic container naming pattern has changed:

# docker-compose v1: uses underscore
myproject_web

# docker compose v2: uses hyphen
myproject-web

This affects scripts that rely on container names and automated image tagging.

Migration Guidelines

1. Update Your Scripts

Replace all instances of docker-compose with docker compose in your scripts and documentation.

2. Adjust Environment Configuration

If you use separate directories for Compose files and environment files, either:

• Move your .env file to the Compose file directory
• Use explicit paths in your env_file declarations
• Use the --env-file flag to specify the path

3. Update Container Name References

If your scripts rely on automatically generated container names, update them to use the new naming convention (hyphens instead of underscores).

4. Consider Configuration Updates

While both versions support multiple Compose file formats, v2 prefers compose.yml over docker-compose.yml. Consider renaming your files for consistency.

When to Stick with Legacy Version

In most cases, migrating to docker compose v2 is recommended. However, you might temporarily need the legacy version if:

• You have complex scripts that cannot be immediately updated
• You're working with very old Compose file formats
• You need specific behaviors that changed significantly in v2

Deprecation Notice

Docker-compose v1 is deprecated and no longer receives updates. New features and security fixes are only available in v2.

Verifying Your Installation

Check which version you're running:

# Check docker compose version
docker compose version

# Check if legacy docker-compose is installed
docker-compose version

Conclusion

The transition from docker-compose to docker compose represents Docker's effort to better integrate Compose functionality into the core Docker platform. While there are some behavioral differences that require attention during migration, the new version offers better performance, tighter integration, and ongoing support.

For new projects, always use docker compose v2. For existing projects, plan a migration that addresses the specific behavioral changes discussed above, particularly around environment file handling and naming conventions.