1. Overview
Containerization has become a cornerstone of efficient and scalable application deployment. Docker Compose simplifies this process as a tool for defining and running multi-container Docker applications.
However, as with any tool, developers and DevOps engineers may encounter roadblocks — one such issue being the frustrating docker-compose: command not found error.
Several things can cause this disruptive issue, ranging from misconfigured environments to missing installations. In this tutorial, we’ll explore the root causes of the docker-compose: command not found error.
2. Problem Outline
Docker Compose is a tool used for defining and running multi-container Docker applications. We can either use it as a standalone tool as docker-compose, or we can use it via the Docker CLI’s Compose plugin as docker compose.
The docker-compose: command not found error typically arises when Docker Compose is either not installed correctly or when its binary isn’t included in the system’s PATH. Thus, there are several contributing factors to this problem, such as an incomplete installation, incorrect environment configuration, or missing symbolic links.
If our docker-compose installation isn’t correct, when we try to use it, we’ll get the following error:
$ docker-compose up
docker-compose: command not found
This output indicates an issue with our docker-compose installation.
3. Verify Docker Compose Installation
Before diving into more complex solutions, we should verify that docker-compose is installed on the system. One way to do this is by attempting to check the version:
$ docker-compose --version
Docker Compose version v2.29.2
This command outputs the version of docker-compose if the tool is correctly installed. However, if it isn’t installed, we’ll see the command not found error instead.
4. Installing Standalone docker-compose
Let’s explore installing the standalone docker-compose tool on a Linux system. Generally, the standalone docker-compose tool is more common on Linux systems. We should now favor the compose plugin in the Docker CLI for Windows and macOS.
4.1. Installing docker-compose via Binary
First, let’s download the Docker Compose binary:
$ sudo curl -L \
https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) \
-o /usr/local/bin/docker-compose
This command downloads the latest version of Docker Compose.
Subsequently, let’s apply executable permissions to the binary:
$ sudo chmod +x /usr/local/bin/docker-compose
This command grants executable permissions to the docker-compose binary located at /usr/local/bin, allowing it to be run as a program. Then, we can verify the installation of docker-compose by checking the version.
4.2. Installing docker-compose via APT
We can also install Docker Compose directly from the APT package manager. Let’s go ahead and install Docker Compose:
$ sudo apt install docker-compose
This command installs the latest version of docker-compose on our Linux system.
5. Adding Docker Compose to the System PATH
If we’re still facing issues after installing docker-compose, the problem might be related to the system PATH. Therefore, let’s resolve this issue by adding Docker Compose to the system PATH.
5.1. On Linux and macOS
We can add Docker Compose to our PATH by editing the .bashrc, .bash_profile, or .zshrc file (depending on our shell). Let’s start by adding the directory the docker-compose binary is commonly located within to the .bashrc file:
export PATH=$PATH:/usr/local/bin
Verifying that the binary’s directory is also on the PATH allows the shell to identify and execute the command. After saving the profile file, we can apply the changes and reload the shell configuration:
$ source ~/.bashrc
Once completed, we should verify the Docker Compose installation as discussed previously.
5.2. On Windows
On the Windows system, we can modify the PATH environment variable by navigating to System Properties > Environment Variables > System Variables and then adding the path to Docker Compose to the PATH variable. This path is typically C:\Program Files\Docker\Docker\resources\bin, but it could vary based on where Docker has been installed.
6. Installing the Docker CLI and Compose Plugin
The Docker CLI now integrates the newer Docker Compose plugin, streamlining the installation process. Therefore, starting with Docker 1.5 or later, there’s no need to install the standalone docker-compose separately.
6.1.Installation in Linux
Before proceeding with the installation on a Linux-based system, let’s verify the presence of the Docker Compose plugin:
$ docker compose version
This command outputs the version number of the Docker Compose plugin if installed. If we get an error, we should install or upgrade the Docker Engine. Let’s install and upgrade the Docker Engine:
$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io
These commands update the package list and then install Docker Engine, Docker CLI, and containerd on a Linux-based system. After the installation, we can verify the installation again by running the docker compose version command as shown earlier. For Docker version 1.5 or later, we should always use the docker compose command instead of docker-compose to utilize the newer plugin.
6.2. Installation in macOS or Windows
If we’re using macOS or Windows, Docker Desktop includes the Docker Compose plugin by default. Therefore, we should make sure that Docker Desktop is installed and updated.
To verify the installation on macOS, we check the /Applications directory for the Docker application. On Windows, we look in the C:\Program Files folder for Docker.
Note that these instructions assume that the user has installed Docker Desktop in the default location, but it could be installed somewhere else.
Another way is to use the OS-specific command prompt to verify the Docker Desktop installation for both macOS and Windows:
docker --version
If Docker Desktop is installed, this command will return the installed Docker version. If we still encounter the error, we should reinstall Docker Desktop and restart our system.
7. Handling User-Specific Installations
If only the root user (and not a regular user) installs Docker Compose, that can cause errors when running Docker Compose commands. To begin with, let’s run Docker Compose in user mode:
$ docker-compose --version
zsh: permission denied: docker-compose
This output indicates that the user doesn’t have the necessary permissions to execute the docker-compose command. To clarify, let’s first check the location of the docker-compose executable:
$ sudo which docker-compose
/usr/local/bin/docker-compose
This command first outputs the location of the docker-compose executable file. With this information, let’s check the file’s permissions to determine whether they are restrictive for the user:
$ sudo ls -la /usr/local/bin/docker-compose
-rwxr-x--- 1 root root 63173250 Aug 20 01:47 /usr/local/bin/docker-compose
From the output, we notice that the file is only accessible to the root user and members of the root group. Therefore, let’s add execution permissions for a user to use docker-compose:
$ sudo chmod o+rx /usr/local/bin/docker-compose
This command adds read (r) and execute (x) permissions for all users on the system, making docker-compose executable by non-root users. Finally, let’s run the docker-compose command as a regular user to verify it:
$ docker-compose --version
Docker Compose version v2.29.2
From the output, we can notice that the docker-compose command now runs successfully in user mode.
8. Conclusion
In this article, we explored various methods to resolve the docker-compose: command not found error.
Although encountering this error can be a hassle, we can resolve it once we understand the underlying causes. By verifying the installation, adjusting PATH variables, ensuring proper permissions, and keeping tools updated, we can quickly fix our docker-compose command and continue with our development.