docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/compose/install.md

8.3 KiB
Raw Blame History

description keywords title
How to install Docker Compose compose, orchestration, install, installation, docker, documentation Install Docker Compose

You can run Compose on macOS, Windows and 64-bit Linux. To install it, you'll need to install Docker first.

To install Compose, do the following:

  1. Install Docker Engine:

  2. Docker for Mac, Docker for Windows, and Docker Toolbox include Docker Compose, so most Mac and Windows users do not need to install Docker Compose separately.

    If you are running the Docker daemon and client directly on Microsoft Windows Server 2016 (with Docker EE for Windows Server 2016, you do need to install Docker Compose.

    To do this, 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.

    Run the following command to download Docker Compose, replacing $dockerComposeVersion with the specific version of Compose you want to use:

    Invoke-WebRequest "https://github.com/docker/compose/releases/download/$dockerComposeVersion/docker-compose-Windows-x86_64.exe" -UseBasicParsing -OutFile $Env:ProgramFiles\docker\docker-compose.exe

    For example, to download Compose version {{ site.compose_current }}, the command is:

    Invoke-WebRequest "https://github.com/docker/compose/releases/download/{{site.compose_current}}/docker-compose-Windows-x86_64.exe" -UseBasicParsing -OutFile $Env:ProgramFiles\docker\docker-compose.exe

    Use the latest Compose release number in the download command.

    As already mentioned, the above command is an example, and it may become out-of-date once in a while. Always follow the command pattern shown above it. If you cut-and-paste an example, check which release it specifies and, if needed, replace $dockerComposeVersion with the release number that you want. Compose releases are also available for direct download on the Compose repository release page on GitHub{:target="blank" class=""}. {: .important}

    Now, run the executable to install Compose.

  3. On Linux, you can download the Docker Compose binary from the Compose repository release page on GitHub{: target="blank" class=""}. Follow the instructions from the link, which involve running the curl command in your terminal to download the binaries.

    Got a "Permission denied" error?

    If so, your /usr/local/bin directory probably isn't writable and you'll need to install Compose as the superuser. Run sudo -i, then run the download and install commands below, then exit.

    Run this command to download Docker Compose, replacing $dockerComposeVersion with the specific version of Compose you want to use:

    curl -L https://github.com/docker/compose/releases/download/$dockerComposeVersion/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose

    For example, to download Compose version {{site.compose_current}}, the command is:

    curl -L https://github.com/docker/compose/releases/download/{{site.compose_current}}/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose

    Use the latest Compose release number in the download command.

    The above command is an example, and it may become out-of-date once in a while. Always follow the command pattern shown above it. If you cut-and-paste an example, check which release it specifies and, if needed, replace $dockerComposeVersion with the release number that you want. Compose releases are also available for direct download on the Compose repository release page on GitHub{: target="blank" class=""}. {: .important}

    If you have problems installing with curl, see Alternative Install Options.

  4. Apply executable permissions to the binary:

    sudo chmod +x /usr/local/bin/docker-compose

  5. Optionally, install command completion for the bash and zsh shell.

  6. Test the installation.

    $ docker-compose --version
docker-compose version {{site.compose_current}}, build 1719ceb

Alternative install options

Install using pip

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. Be sure to replace the version number with the one that you want, if this example is out-of-date:

$ curl -L --fail https://github.com/docker/compose/releases/download/{{site.compose_current}}/run.sh > /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose

Use the latest Compose release number in the download command.

The above command is an example, and it may become out-of-date once in a while. Check which release it specifies and, if needed, 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{: target="blank" class=""}. {: .important}

Master builds

If you're interested in trying out a pre-release build you can download a binary from 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, you'll need to 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 so they need to be recreated with labels added.

If Compose detects containers that were created without labels, it will refuse 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 will just create new ones.

docker 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, prepend sudo to either of the above commands and run again.

Where to go next