How to Install Docker CLI and Docker Compose CLI on macOS

How to Install Docker CLI and Docker Compose CLI on macOS

If you need Docker without Docker Desktop, on macOS it’s convenient to install only the Docker CLI and a separate Docker Compose CLI. This setup works well alongside Colima or a remote Docker Engine: you get the docker command, plus the modern docker compose command.

Quick Overview

For macOS without Docker Desktop, this set is enough:

brew install docker docker-compose

mkdir -p ~/.docker/cli-plugins
ln -sfn $(brew --prefix)/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose
docker compose version

This is a simple and practical way to get the Docker CLI and Docker Compose CLI in your terminal without extra components.

What You’ll Need

Before installing, make sure you have Homebrew. It’s the easiest way to install and update the packages you need on macOS. If Homebrew is already installed, you can move straight to the next step.

It also helps to understand the difference between the components:

  • Docker CLI — the docker client command.
  • Docker Compose CLI — a plugin that adds docker compose.
  • Docker Desktop — a separate app with a GUI and built-in Compose support.

If you only need the terminal, Docker Desktop is not required.

Installing Docker CLI

First, install the Docker CLI:

brew install docker

After this, the docker command becomes available in your terminal. However, this alone isn’t enough for docker compose, since Compose is installed separately.

Check the installation:

docker version

If you already have a Docker Engine running, this command will show client and server information. If there’s no server, that’s normal when you’re using Colima or a remote daemon.

Installing Docker Compose CLI

Now install Docker Compose:

brew install docker-compose

On macOS with Homebrew, this package usually installs the Compose binary itself, which can be connected as a CLI plugin. For the docker compose command to work in the modern format, you need to make it visible to the Docker CLI.

Create the plugins directory and add a symlink:

mkdir -p ~/.docker/cli-plugins

ln -sfn $(brew --prefix)/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

Then check it:

docker compose version

If everything is set up correctly, you’ll see the Docker Compose version.

Verifying It Works

After installation, check the basic commands:

docker version
docker compose version
docker compose ps

If docker version works and docker compose version also responds correctly, both components are installed and linked properly.

If You Use Colima

For Colima, you usually don’t need to do anything extra if the Docker CLI is already pointing to the right context. You might have a local Docker Engine via Colima, with Compose working on top of it as a regular subcommand.

It’s useful to check the current context:

docker context ls
docker context show

If default or the desired Colima context is active, you can go ahead and run docker compose up.

Possible problems

If the docker compose command isn’t recognized, the cause is usually one of three things:

  • The Compose package isn’t installed.
  • The plugin isn’t located in ~/.docker/cli-plugins.
  • The symlink points to the wrong place or was broken after a Homebrew update.

In that case, repeat the installation commands and check the path:

ls -l ~/.docker/cli-plugins/

brew --prefix
docker  macos  devops