Skip to content
This repository has been archived by the owner on Jun 16, 2021. It is now read-only.
/ libcompose Public archive

*Unmaintained/Deprecated* An experimental go library providing Compose-like functionality


Notifications You must be signed in to change notification settings


Repository files navigation

⚠️ Deprecation Notice: This project and repository is now deprecated and is no longer under active development. Please use compose-go instead.


GoDoc Build Status

A Go library for Docker Compose. It does everything the command-line tool does, but from within Go -- read Compose files, start them, scale them, etc.

Note: This is not really maintained anymore — the reason are diverse but mainly lack of time from the maintainers

The current state is the following :

  • The libcompose CLI should considered abandonned. The v2 parsing is incomplete and v3 parsing is missing.
  • The official compose Go parser implementation is on docker/cli but only support v3 version of the compose format.

What is the work that is needed:

  • Remove the cli code (thus removing dependencies to docker/cli )
  • Clearer separation of packages : parsing, conversion (to docker api or swarm api), execution (Up, Down, … behaviors)
  • Add support for all compose format version (v1, v2.x, v3.x)
  • Switch to either golang/dep or go mod for dependencies (removing the vendor folder)
  • (bonus) extract the docker/cli code here and vendor this library into docker/cli.

If you are interested to work on libcompose, feel free to ping me (over twitter @vdemeest), I'll definitely do code reviews and help as much as I can 😉.

Note: This is experimental and not intended to replace the Docker Compose command-line tool. If you're looking to use Compose, head over to the Compose installation instructions to get started with it.

Here is a list of known project that uses libcompose:


package main

import (



func main() {
	project, err := docker.NewProject(&ctx.Context{
		Context: project.Context{
			ComposeFiles: []string{"docker-compose.yml"},
			ProjectName:  "my-compose",
	}, nil)

	if err != nil {

	err = project.Up(context.Background(), options.Up{})

	if err != nil {


You need either Docker and make, or go in order to build libcompose.

Building with docker

You need Docker and make and then run the binary target. This will create binary for all platform in the bundles folder.

$ make binary
docker build -t "libcompose-dev:refactor-makefile" .
# […]
---> Making bundle: binary (in .)
Number of parallel builds: 4

-->      darwin/386:
-->    darwin/amd64:
-->       linux/386:
-->     linux/amd64:
-->       linux/arm:
-->     windows/386:
-->   windows/amd64:

$ ls bundles
libcompose-cli_darwin-386*    libcompose-cli_linux-amd64*      libcompose-cli_windows-amd64.exe*
libcompose-cli_darwin-amd64*  libcompose-cli_linux-arm*
libcompose-cli_linux-386*     libcompose-cli_windows-386.exe*

Building with go

  • You need go v1.11 or greater
  • you need to set export GO111MODULE=on environment variable
  • If your working copy is not in your GOPATH, you need to set it accordingly.
$ go generate
# Generate some stuff
$ go build -o libcompose ./cli/main


A partial implementation of the libcompose-cli CLI is also implemented in Go. The primary purpose of this code is so one can easily test the behavior of libcompose.

Run one of these:


Tests (unit & integration)

You can run unit tests using the test-unit target and the integration test using the test-integration target. If you don't use Docker and make to build libcompose, you can use go test and the following scripts : hack/test-unit and hack/test-integration.

$ make test-unit
docker build -t "libcompose-dev:refactor-makefile" .
---> Making bundle: test-unit (in .)
+ go test -cover -coverprofile=cover.out ./docker
ok     0.019s  coverage: 4.6% of statements
+ go test -cover -coverprofile=cover.out ./project
ok    0.010s  coverage: 8.4% of statements
+ go test -cover -coverprofile=cover.out ./version
ok    0.002s  coverage: 0.0% of statements

Test success

Current status

The project is still being kickstarted... But it does a lot. Please try it out and help us find bugs.


Want to hack on libcompose? Docker's contributions guidelines apply.

If you have comments, questions, or want to use your knowledge to help other, come join the conversation on IRC. You can reach us at #libcompose on Freenode.