Install Docker Compose
Estimated reading time: 7 minutesYou can run Compose on macOS, Windows, and 64-bit Linux.
Prerequisites
Docker Compose relies on Docker Engine for any meaningful work, so make sure you have Docker Engine installed either locally or remote, depending on your setup.
-
On desktop systems like Docker Desktop for Mac and Windows, Docker Compose is included as part of those desktop installs.
-
On Linux systems, first install the Docker for your OS as described on the Get Docker page, then come back here for instructions on installing Compose on Linux systems.
-
To run Compose as a non-root user, see Manage Docker as a non-root user.
Install Compose
Follow the instructions below to install Compose on Mac, Windows, Windows Server
2016, or Linux systems, or find out about alternatives like using the pip
Python package manager or installing Compose as a container.
Install a different version
The instructions below outline installation of the current stable release (v1.24.0) of Compose. To install a different version of Compose, replace the given release number with the one that you want. Compose releases are also listed and available for direct download on the Compose repository release page on GitHub. To install a pre-release of Compose, refer to the install pre-release builds section.
Install Compose on macOS
Docker Desktop for Mac and Docker Toolbox already include Compose along with other Docker apps, so Mac users do not need to install Compose separately. Docker install instructions for these are here:
- Get Docker Desktop for Mac
- Get Docker Toolbox (for older systems)
Install Compose on Windows desktop systems
Docker Desktop for Windows and Docker Toolbox already include Compose along with other Docker apps, so most Windows users do not need to install Compose separately. Docker install instructions for these are here:
- Get Docker Desktop for Windows
- Get Docker Toolbox (for older systems)
If you are running the Docker daemon and client directly on Microsoft Windows Server, follow the instructions in the Windows Server tab.
Install Compose on Windows Server
Follow these instructions if you are running the Docker daemon and client directly on Microsoft Windows Server with Docker Engine - Enterprise, and want to install Docker Compose.
-
Start an “elevated” PowerShell (run it as administrator). Search for PowerShell, right-click, and choose Run as administrator. When asked if you want to allow this app to make changes to your device, click Yes.
-
In PowerShell, since GitHub now requires TLS1.2, run the following:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Then run the following command to download the current stable release of Compose (v1.24.0):
Invoke-WebRequest "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-Windows-x86_64.exe" -UseBasicParsing -OutFile $Env:ProgramFiles\Docker\docker-compose.exe
Note: On Windows Server 2019, you can add the Compose executable to $Env:ProgramFiles\Docker
. Because this directory is registered in the system PATH
, you can run the docker-compose --version
command on the subsequent step with no additional configuration.
> To install a different version of Compose, substitute `1.24.0`
> with the version of Compose you want to use.
-
Test the installation.
docker-compose --version docker-compose version 1.24.0, build 01110ad01
Install Compose on Linux systems
On Linux, you can download the Docker Compose binary from the Compose
repository release page on GitHub. Follow the instructions from the link, which involve
running the curl
command in your terminal to download the binaries. These step-by-step instructions are also included below.
For
alpine
, the following dependency packages are needed:py-pip
,python-dev
,libffi-dev
,openssl-dev
,gcc
,libc-dev
, andmake
.
-
Run this command to download the current stable release of Docker Compose:
sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
To install a different version of Compose, substitute
1.24.0
with the version of Compose you want to use.If you have problems installing with
curl
, see Alternative Install Options tab above. -
Apply executable permissions to the binary:
sudo chmod +x /usr/local/bin/docker-compose
Note: If the command
docker-compose
fails after installation, check your path. You can also create a symbolic link to/usr/bin
or any other directory in your path.
For example:
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
-
Optionally, install command completion for the
bash
andzsh
shell. -
Test the installation.
$ docker-compose --version docker-compose version 1.24.0, build 1110ad01
Alternative install options
Install using pip
For
alpine
, the following dependency packages are needed:py-pip
,python-dev
,libffi-dev
,openssl-dev
,gcc
,libc-dev
, andmake
.
Compose can be installed from
pypi using pip
. If you install
using pip
, we recommend that you use a
virtualenv because many operating
systems have python system packages that conflict with docker-compose
dependencies. See the virtualenv
tutorial to get
started.
pip install docker-compose
If you are not using virtualenv,
sudo pip install docker-compose
pip version 6.0 or greater is required.
Install as a container
Compose can also be run inside a container, from a small bash script wrapper. To install compose as a container run this command:
$ sudo curl -L --fail https://github.com/docker/compose/releases/download/1.24.0/run.sh -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
Install pre-release builds
If you’re interested in trying out a pre-release build, you can download release
candidates from the Compose repository release page on GitHub.
Follow the instructions from the link, which involves running the curl
command
in your terminal to download the binaries.
Pre-releases built from the “master” branch are also available for download at https://dl.bintray.com/docker-compose/master/.
Pre-release builds allow you to try out new features before they are released, but may be less stable.
Upgrading
If you’re upgrading from Compose 1.2 or earlier, remove or migrate your existing containers after upgrading Compose. This is because, as of version 1.3, Compose uses Docker labels to keep track of containers, and your containers need to be recreated to add the labels.
If Compose detects containers that were created without labels, it refuses to run, so that you don’t end up with two sets of them. If you want to keep using your existing containers (for example, because they have data volumes you want to preserve), you can use Compose 1.5.x to migrate them with the following command:
docker-compose migrate-to-labels
Alternatively, if you’re not worried about keeping them, you can remove them. Compose just creates new ones.
docker container rm -f -v myapp_web_1 myapp_db_1 ...
Uninstallation
To uninstall Docker Compose if you installed using curl
:
sudo rm /usr/local/bin/docker-compose
To uninstall Docker Compose if you installed using pip
:
pip uninstall docker-compose
Got a “Permission denied” error?
If you get a “Permission denied” error using either of the above methods, you probably do not have the proper permissions to remove
docker-compose
. To force the removal, prependsudo
to either of the above commands and run again.
Where to go next
- User guide
- Getting Started
- Get started with Django
- Get started with Rails
- Get started with WordPress
- Command line reference
- Compose file reference