title
Getting started with the Engine API

To try out the Docker Engine API in development, you first need to install Docker.

Next, you need to install an SDK for the language you are using. There are official ones available for Python and Go, and a number of community maintained libraries for other languages. Head to the SDKs page to find and install them.

Running a container

The most basic thing you can do with Docker is running a container. On the command line, you would use the docker run command, but this is just as easy to do from your own apps too.

This is the equivalent of doing docker run alpine echo hello world:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() print client.containers.run("alpine", ["echo", "hello", "world"]) {% endhighlight %}

{% highlight go %} package main

import ( "io" "os"

"github.com/docker/engine-api/client"
"github.com/docker/engine-api/types"
"github.com/docker/engine-api/types/container"
"golang.org/x/net/context"

)

func main() { ctx := context.Background() cli, err := client.NewEnvClient() if err != nil { panic(err) }

_, err = cli.ImagePull(ctx, "alpine", types.ImagePullOptions{})
if err != nil {
	panic(err)
}

resp, err := cli.ContainerCreate(ctx, &container.Config{
	Image: "alpine",
	Cmd:   []string{"echo", "hello world"},
}, nil, nil, "")
if err != nil {
	panic(err)
}

if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil {
	panic(err)
}

if _, err = cli.ContainerWait(ctx, resp.ID); err != nil {
	panic(err)
}

out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true})
if err != nil {
	panic(err)
}

io.Copy(os.Stdout, out)

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \ -d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \ -X POST http:/v1.24/containers/create {"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start

$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/wait {"StatusCode":0}

$ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/1c6594faf5/logs?stdout=1" hello world {% endhighlight %}

You can also run containers in the background, the equivalent of docker run -d bfirsh/reticulate-splines:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() container = client.containers.run("bfirsh/reticulate-splines", detach=True) print container.id {% endhighlight %}

{% highlight go %} package main

import ( "fmt" "io" "os"

"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/client"
"golang.org/x/net/context"

)

func main() { ctx := context.Background() cli, err := client.NewEnvClient() if err != nil { panic(err) }

imageName := "bfirsh/reticulate-splines"

out, err := cli.ImagePull(ctx, imageName, types.ImagePullOptions{})
if err != nil {
	panic(err)
}
io.Copy(os.Stdout, out)

resp, err := cli.ContainerCreate(ctx, &container.Config{
	Image: imageName,
}, nil, nil, "")
if err != nil {
	panic(err)
}

if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil {
	panic(err)
}

fmt.Println(resp.ID)

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \ -d '{"Image": "bfirsh/reticulate-splines"}' \ -X POST http:/v1.24/containers/create {"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http:/v1.24/containers/1c6594faf5/start {% endhighlight %}

Listing and managing containers

Like docker ps, we can use the API to list containers that are running:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() for container in client.containers.list(): print container.id {% endhighlight %}

{% highlight go %} package main

import ( "context" "fmt"

"github.com/docker/docker/api/types"
"github.com/docker/docker/client"

)

func main() { cli, err := client.NewEnvClient() if err != nil { panic(err) }

containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
if err != nil {
	panic(err)
}

for _, container := range containers {
	fmt.Println(container.ID)
}

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock http:/v1.24/containers/json [{ "Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772", "Names":["/tender_wing"], "Image":"bfirsh/reticulate-splines", ... }]

{% endhighlight %}

Now we know what containers exist, we can perform operations on them. For example, we can stop all running containers:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() for container in client.containers.list(): container.stop() {% endhighlight %}

{% highlight go %} package main

import ( "context"

"github.com/docker/docker/api/types"
"github.com/docker/docker/client"

)

func main() { ctx := context.Background() cli, err := client.NewEnvClient() if err != nil { panic(err) }

containers, err := cli.ContainerList(ctx, types.ContainerListOptions{})
if err != nil {
	panic(err)
}

for _, container := range containers {
	if err := cli.ContainerStop(ctx, container.ID, nil); err != nil {
		panic(err)
	}
}

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock http:/v1.24/containers/json [{ "Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772", "Names":["/tender_wing"], "Image":"bfirsh/reticulate-splines", ... }]

$ curl --unix-socket /var/run/docker.sock
-X POST http:/v1.24/containers/ae63e8b89a26/stop

{% endhighlight %}

We can also perform actions on individual containers. For example, to print the logs of a container given its ID:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() container = client.containers.get('f1064a8a4c82') print container.logs() {% endhighlight %}

{% highlight go %} package main

import ( "context" "io" "os"

"github.com/docker/docker/api/types"
"github.com/docker/docker/client"

)

func main() { ctx := context.Background() cli, err := client.NewEnvClient() if err != nil { panic(err) }

options := types.ContainerLogsOptions{ShowStdout: true}
out, err := cli.ContainerLogs(ctx, "f1064a8a4c82", options)
if err != nil {
	panic(err)
}

io.Copy(os.Stdout, out)

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock "http:/v1.24/containers/ca5f55cdb/logs?stdout=1" Reticulating spline 1... Reticulating spline 2... Reticulating spline 3... Reticulating spline 4... Reticulating spline 5... {% endhighlight %}

Managing images

Images are the basis of containers, and can be managed in a similar way. You can list the images on your Engine, similar to docker images:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() for image in client.images.list(): print image.id {% endhighlight %}

{% highlight go %} package main

import ( "context" "fmt"

"github.com/docker/docker/api/types"
"github.com/docker/docker/client"

)

func main() { cli, err := client.NewEnvClient() if err != nil { panic(err) }

images, err := cli.ImageList(context.Background(), types.ImageListOptions{})
if err != nil {
	panic(err)
}

for _, image := range images {
	fmt.Println(image.ID)
}

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock http:/v1.24/images/json [{ "Id":"sha256:31d9a31e1dd803470c5a151b8919ef1988ac3efd44281ac59d43ad623f275dcd", "ParentId":"sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96", ... }] {% endhighlight %}

You can pull images, like docker pull:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() image = client.images.pull("alpine") print image.id {% endhighlight %}

{% highlight go %} package main

import ( "io" "os"

"github.com/docker/docker/api/types"
"github.com/docker/docker/client"
"golang.org/x/net/context"

)

func main() { ctx := context.Background() cli, err := client.NewEnvClient() if err != nil { panic(err) }

out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{})
if err != nil {
	panic(err)
}

io.Copy(os.Stdout, out)

} {% endhighlight %}

{% highlight bash %} $ curl --unix-socket /var/run/docker.sock \ -X POST "http:/v1.24/images/create?fromImage=alpine" {"status":"Pulling from library/alpine","id":"3.1"} {"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"} {"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e ] 32.77 kB/2.244 MB","id":"8f13703509f7"} ... {% endhighlight %}

And commit containers to create images from their contents:

Python

Go

curl

{% highlight python %} import docker client = docker.from_env() container = client.run("alpine", ["touch", "/helloworld"], detached=True) container.wait() image = container.commit("helloworld") print image.id {% endhighlight %}

{% highlight go %} package main

import ( "fmt"

"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/container"
"github.com/docker/docker/client"
"golang.org/x/net/context"

)

func main() { ctx := context.Background() cli, err := client.NewEnvClient() if err != nil { panic(err) }

createResp, err := cli.ContainerCreate(ctx, &container.Config{
	Image: "alpine",
	Cmd:   []string{"touch", "/helloworld"},
}, nil, nil, "")
if err != nil {
	panic(err)
}

if err := cli.ContainerStart(ctx, createResp.ID, types.ContainerStartOptions{}); err != nil {
	panic(err)
}

if _, err = cli.ContainerWait(ctx, createResp.ID); err != nil {
	panic(err)
}

commitResp, err := cli.ContainerCommit(ctx, createResp.ID, types.ContainerCommitOptions{Reference: "helloworld"})
if err != nil {
	panic(err)
}

fmt.Println(commitResp.ID)

} {% endhighlight %}

{% highlight bash %} $ docker run -d alpine touch /helloworld 0888269a9d584f0fa8fc96b3c0d8d57969ceea3a64acf47cd34eebb4744dbc52 $ curl --unix-socket /var/run/docker.sock\ -X POST "http:/v1.24/commit?container=0888269a9d&repo=helloworld" {"Id":"sha256:6c86a5cd4b87f2771648ce619e319f3e508394b5bfc2cdbd2d60f59d52acda6c"} {% endhighlight %}

Next steps

Full documentation for the Python SDK.
Full documentation for the Go SDK.
Full documentation for the HTTP API.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

getting-started.md

getting-started.md

Running a container

Listing and managing containers

Managing images

Next steps

Files

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

Running a container

Listing and managing containers

Managing images

Next steps