Public Repository

Last pushed: 4 years ago
Short Description
Short description is empty for this repo.
Full Description


An API client for docker written in Python


Our latest stable is always available on PyPi.

pip install docker-py


To instantiate a Client class that will allow you to communicate with
a Docker daemon, simply do:

c = docker.Client(base_url='unix://var/run/docker.sock',

base_url refers to the protocol+hostname+port where the docker server
is hosted. version is the version of the API the client will use and
timeout specifies the HTTP request timeout, in seconds., tag=None, quiet=False, fileobj=None, nocache=False,
        rm=False, stream=False, timeout=None,
        custom_context=False, encoding=None):

Similar to the docker build command. Either path or fileobj needs
to be set. path can be a local path (to a directory containing a
Dockerfile) or a remote URL. fileobj must be a readable file-like
object to a Dockerfile.

If you have a tar file for the docker build context (including a dockerfile)
already, pass a readable file-like object to fileobj and also pass
custom_context=True. If the stream is compressed also, set encoding to
the correct value (e.g gzip).

c.commit(container, repository=None, tag=None, message=None, author=None,

Identical to the docker commit command.

c.containers(quiet=False, all=False, trunc=True, latest=False, since=None,
             before=None, limit=-1)

Identical to the docker ps command.

c.copy(container, resource)

Identical to the docker cp command.

c.create_container(image, command=None, hostname=None, user=None,
                   detach=False, stdin_open=False, tty=False, mem_limit=0,
                   ports=None, environment=None, dns=None, volumes=None,
                   volumes_from=None, network_disabled=False, name=None,
                   entrypoint=None, cpu_shares=None, working_dir=None,

Creates a container that can then be started. Parameters are similar
to those for the docker run command except it doesn't support the
attach options (-a). See "Port bindings" and "Using volumes" below for
more information on how to create port bindings and volume mappings.

volumes_from and dns arguments raise TypeError exception if they are used
against v1.10 of docker remote API. Those arguments should be passed to
start() instead.


Identical to the docker diff command.


Identical to the docker export command.


Identical to the docker history command.

c.images(name=None, quiet=False, all=False, viz=False)

Identical to the docker images command.

c.import_image(src, data=None, repository=None, tag=None)

Identical to the docker import command. If src is a string or
unicode string, it will be treated as a URL to fetch the image from. To
import an image from the local machine, src needs to be a file-like
object or bytes collection. To import from a tarball use your absolute
path to your tarball. To load arbitrary data as tarball use whatever
you want as src and your tarball content in data.

Identical to the docker info command.

c.insert(image, url, path)

Identical to the docker insert command.


Identical to the docker inspect command, but only for containers.


Identical to the docker inspect command, but only for images.

c.kill(container, signal=None)

Kill a container. Similar to the docker kill command.

c.login(username, password=None, email=None, registry=None)

Identical to the docker login command (but non-interactive, obviously).

c.logs(container, stdout=True, stderr=True, stream=False, timestamps=False)

Identical to the docker logs command. The stream parameter makes the
logs function return a blocking generator you can iterate over to
retrieve log output as it happens.

c.attach(container, stdout=True, stderr=True, stream=False, logs=False)

The logs function is a wrapper around this one, which you can use
instead if you want to fetch/stream container output without first
retrieving the entire backlog.

Hits the /_ping endpoint of the remote API and returns the result.
An exception will be raised if the endpoint isn't responding.

c.port(container, private_port)

Identical to the docker port command.

c.pull(repository, tag=None, stream=False)

Identical to the docker pull command.

c.push(repository, stream=False)

Identical to the docker push command.

c.remove_container(container, v=False, link=False)

Remove a container. Similar to the docker rm command.


Remove an image. Similar to the docker rmi command.

c.restart(container, timeout=10)

Restart a container. Similar to the docker restart command.

Identical to the docker search command.

c.start(container, binds=None, port_bindings=None, lxc_conf=None,
        publish_all_ports=False, links=None, privileged=False,
        dns=None, dns_search=None, volumes_from=None, network_mode=None)

Similar to the docker start command, but doesn't support attach
options. Use docker logs to recover stdout/stderr.

binds allows to bind a directory in the host to the container. See
"Using volumes" below for more information. port_bindings exposes
container ports to the host. See "Port bindings" below for more
information. lxc_conf allows to pass LXC configuration options using a
dictionary. privileged starts the container in privileged mode.

can be specified with the links argument. They can either be
specified as a dictionary mapping name to alias or as a list of
(name, alias) tuples.

dns and volumes_from are only available if they are used with version v1.10
of docker remote API. Otherwise they are ignored.

network_mode is available since v1.11 and sets the Network mode for the
container ('bridge': creates a new network stack for the container on the
docker bridge, 'none': no networking for this container, 'container:[name|id]':
reuses another container network stack), 'host': use the host network stack
inside the container.

c.stop(container, timeout=10)

Stops a container. Similar to the docker stop command.

c.tag(image, repository, tag=None, force=False)

Identical to the docker tag command.

Identical to the docker top command.


Identical to the docker version command.


Wait for a container and return its exit code. Similar to the docker wait command.

Port bindings

Port bindings is done in two parts. Firstly, by providing a list of ports to
open inside the container in the Client.create_container method.

c.create_container('busybox', 'ls', ports=[1111, 2222])

Bindings are then declared in the Client.start method.

c.start(container_id, port_bindings={1111: 4567, 2222: None})

You can limit the host address on which the port will be exposed like such:

c.start(container_id, port_bindings={1111: ('', 4567)})

Or without host port assignment:

c.start(container_id, port_bindings={1111: ('',)})

If you wish to use UDP instead of TCP (default), you need to declare it
like such in both the create_container() and start() calls:

container_id = c.create_container('busybox', 'ls', ports=[(1111, 'udp'), 2222])
c.start(container_id, port_bindings={'1111/udp': 4567, 2222: None})

Using volumes

Similarly, volume declaration is done in two parts. First, you have to provide
a list of mountpoints to the Client.create_container method.

c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'])

Volume mappings are then declared inside the Client.start method like this:

c.start(container_id, binds={
            'bind': '/mnt/vol2',
            'ro': False
            'bind': '/mnt/vol1',
            'ro': True
Docker Pull Command