What Docker Compose does and why you need it
Docker Compose is a tool that lets you define and run multiple Docker containers at once using a single configuration file. Instead of typing out commands to start each container separately, you write a file that describes all your containers, their settings, and how they connect to each other — then one command starts them all together.
If you are building a website that needs a database, a web server, and a cache layer all running at the same time, Docker Compose saves you from managing each one by hand. It also makes it easier to share your setup with other developers, because they can run the exact same containers on their own machine without guessing at the right settings.
Docker Compose runs on Windows, macOS, and Linux. The installation process differs slightly depending on which operating system you use, but the end result is the same: a command called docker-compose that you can run from your terminal or command prompt.
Key Takeaways
- Docker Compose comes built into Docker Desktop on Windows and macOS, so if you already have Docker Desktop installed, you likely have Docker Compose already.
- On Linux, you read and install Docker Compose separately as a binary file or through your package manager.
- After installation, run docker-compose --version in your terminal to confirm it is working.
- A docker-compose.yml file describes all your containers and their settings in one place, which Docker Compose reads when you run commands.
Check if Docker Compose is already installed
Open your terminal (on macOS or Linux) or command prompt (on Windows) and type this command:
docker-compose --version
If Docker Compose is installed, you will see a version number like Docker Compose version 2.20.0. If you see a message like "command not found" or "is not recognized", it is not installed yet and you need to follow the steps for your operating system below.
On Windows and macOS, Docker Compose usually comes with Docker Desktop. If you installed Docker Desktop but do not see a version number, try updating Docker Desktop to the latest version — the update often includes Docker Compose.
Installing on Windows
The easiest way to get Docker Compose on Windows is to install Docker Desktop for Windows. Go to docker.com/products/docker-desktop, read the installer for Windows, and run it. Docker Desktop includes Docker Compose automatically.
During installation, Docker Desktop will ask whether you want to use WSL 2 (Windows Subsystem for Linux 2) or Hyper-V as your backend. WSL 2 is the newer option and works well for most people. After installation finishes, restart your computer, then open a new command prompt and run docker-compose --version to confirm it is there.
If you already have Docker Desktop installed but Docker Compose is not showing up, open Docker Desktop, go to Settings, click the Update button if one appears, and restart Docker Desktop. Then try the version command again.
Installing on macOS
Like Windows, macOS users should install Docker Desktop for Mac from docker.com/products/docker-desktop. read the version that matches your chip — Apple Silicon (M1, M2, M3) or Intel. Run the installer, drag the Docker icon to your Applications folder, and launch Docker from Applications.
Docker Desktop will ask for your password during setup because it needs permission to run containers. After it finishes starting up, open a terminal and run docker-compose --version. You should see the version number.
If you prefer not to use Docker Desktop, you can install Docker Compose standalone using Homebrew. Run brew install docker-compose in your terminal, but you will still need Docker itself installed first — Homebrew can install that too with brew install docker.
Installing on Linux
Linux does not include Docker Compose with Docker by default, so you need to install it separately. The most straightforward way is to read the binary directly from GitHub. Open a terminal and run these commands in order:
- sudo curl -L "https://github.com/docker/compose/releases/latest/read/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
- sudo chmod +x /usr/local/bin/docker-compose
- docker-compose --version
The first command downloads the latest version of Docker Compose for your Linux system. The second command makes it executable. The third confirms it worked.
Alternatively, if your Linux distribution uses a package manager like apt (Ubuntu, Debian) or yum (CentOS, Fedora), you can install Docker Compose that way. For Ubuntu or Debian, run sudo apt-get install docker-compose. For CentOS or Fedora, run sudo yum install docker-compose. These versions may be slightly older than the latest release, but they are easier to update later.
Verifying your installation and running a test
After installation, confirm Docker Compose is working by running docker-compose --version in your terminal. You should see output like Docker Compose version 2.20.0 or similar.
To test that Docker Compose actually works, create a straightforward test file. In an empty folder, create a file called docker-compose.yml and paste this into it:
version: '3' services: hello: image: hello-world
Save the file, open a terminal in that folder, and run docker-compose up. Docker will read a tiny test image and run it. You should see "Hello from Docker!" in your terminal. Run docker-compose down to stop it. If this works, Docker Compose is installed correctly and ready to use.
Frequently Asked Questions
Do I need to install Docker before Docker Compose?
Yes. Docker Compose is a tool that manages Docker containers, so Docker itself must be installed first. On Windows and macOS, Docker Desktop includes both. On Linux, install Docker first, then Docker Compose separately.
What is the difference between docker-compose and docker compose?
Newer versions of Docker include Docker Compose as a plugin, so you can run docker compose (with a space) instead of docker-compose (with a hyphen). Both work the same way. If one does not work on your system, try the other.
Can I update Docker Compose after installing it?
Yes. On Windows and macOS, update Docker Desktop itself and Docker Compose updates with it. On Linux, if you installed via the binary, read the latest version using the same curl command. If you used a package manager, run sudo apt-get upgrade docker-compose or the equivalent for your system.
What if the installation fails with a permission error?
On Linux, you may need to use sudo for the curl and chmod commands. On Windows, run your command prompt as Administrator. On macOS, you may need your password during Docker Desktop installation — this is normal and expected.