Client API

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

from docker import Client
c = Client(base_url='unix://var/run/docker.sock')

Params:

base_url (str): Refers to the protocol+hostname+port where the Docker server is hosted.
version (str): The version of the API the client will use
timeout (int): The HTTP request timeout, in seconds.
tls (bool or TLSConfig): Equivalent CLI options: docker --tls ...

attach

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

Params:

container (str): The container to attach to
stdout (bool): Get STDOUT
stderr (bool): Get STDERR
stream (bool): Return an interator
logs (bool): Get all previous output

Returns (generator or str): The logs or output for the image

build

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).

Params:

path (str): Path to the directory containing the Dockerfile
tag (str): A tag to add to the final image
quiet (bool): Whether to return the status
fileobj: A file object to use as the Dockerfile. (Or a file-like object)
nocache (bool): Don't use the cache when set to True
rm (bool): Remove intermediate containers
stream (bool): Return a blocking generator you can iterate over to retrieve build output as it happens
timeout (int): HTTP timeout
custom_context (bool): Optional if using fileobj
encoding (str): The encoding for a stream. Set to gzip for compressing
pull (bool): Downloads any updates to the FROM image in Dockerfiles

Returns (generator): A generator of the build output

>>> from io import BytesIO
>>> from docker import Client
>>> dockerfile = '''
... # Shared Volume
... FROM busybox:buildroot-2014.02
... MAINTAINER first last, first.last@yourdomain.com
... VOLUME /data
... CMD ["/bin/sh"]
... '''
>>> f = BytesIO(dockerfile.encode('utf-8'))
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> response = [line for line in cli.build(
...     fileobj=f, rm=True, tag='yourname/volume'
... )]
>>> response
['{"stream":" ---\\u003e a9eb17255234\\n"}',
'{"stream":"Step 1 : MAINTAINER first last, first.last@yourdomain.com\\n"}',
'{"stream":" ---\\u003e Running in 08787d0ee8b1\\n"}',
'{"stream":" ---\\u003e 23e5e66a4494\\n"}',
'{"stream":"Removing intermediate container 08787d0ee8b1\\n"}',
'{"stream":"Step 2 : VOLUME /data\\n"}',
'{"stream":" ---\\u003e Running in abdc1e6896c6\\n"}',
'{"stream":" ---\\u003e 713bca62012e\\n"}',
'{"stream":"Removing intermediate container abdc1e6896c6\\n"}',
'{"stream":"Step 3 : CMD [\\"/bin/sh\\"]\\n"}',
'{"stream":" ---\\u003e Running in dba30f2a1a7e\\n"}',
'{"stream":" ---\\u003e 032b8b2855fc\\n"}',
'{"stream":"Removing intermediate container dba30f2a1a7e\\n"}',
'{"stream":"Successfully built 032b8b2855fc\\n"}']

Raises: TypeError if path nor fileobj are specified

commit

Identical to the docker commit command.

Params:

container (str): The image hash of the container
repository (str): The repository to push the image to
tag (str): The tag to push
message (str): A commit message
author (str): The name of the author
conf (dict): The configuraton for the container. See the Docker remote api for full details.

containers

List containers. Identical to the docker ps command.

Params:

quiet (bool): Only display numeric Ids
all (bool): Show all containers. Only running containers are shown by default
trunc (bool): Truncate output
latest (bool): Show only the latest created container, include non-running ones.
since (str): Show only containers created since Id or Name, include non-running ones
before (str): Show only container created before Id or Name, include non-running ones
limit (int): Show limit last created containers, include non-running ones
size (bool): Display sizes

Returns (dict): The system's containers

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.containers()
[{'Command': '/bin/sleep 30',
  'Created': 1412574844,
  'Id': '6e276c9e6e5759e12a6a9214efec6439f80b4f37618e1a6547f28a3da34db07a',
  'Image': 'busybox:buildroot-2014.02',
  'Names': ['/grave_mayer'],
  'Ports': [],
  'Status': 'Up 1 seconds'}]

copy

Identical to the docker cp command. Get files/folders from the container.

Params:

container (str): The container to copy from
resource (str): The path within the container

Returns (str): The contents of the file as a string

create_container

Creates a container that can then be .start() ed. 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 for more information on how to create port bindings and volume mappings.

The mem_limit variable accepts float values (which represent the memory limit of the created container in bytes) or a string with a units identification char ('100000b', 1000k', 128m', '1g'). If a string is specified without a units character, bytes are assumed as an intended unit.

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

Params:

image (str): The image to run
command (str or list): The command to be run in the container
hostname (str): Optional hostname for the container
user (str or int): Username or UID
detach (bool): Detached mode: run container in the background and print new container Id
stdin_open (bool): Keep STDIN open even if not attached
tty (bool): Allocate a pseudo-TTY
mem_limit (float or str): Memory limit (format: [number][optional unit], where unit = b, k, m, or g)
ports (list of ints): A list of port numbers
environment (dict or list): A dictionary or a list of strings in the following format ["PASSWORD=xxx"] or {"PASSWORD": "xxx"}.
dns (list): DNS name servers
volumes (str or list):
volumes_from (str or list): List of container names or Ids to get volumes from. Optionally a single string joining container id's with commas
network_disabled (bool): Disable networking
name (str): A name for the container
entrypoint (str or list): An entrypoint
cpu_shares (int or float): CPU shares (relative weight)
working_dir (str): Path to the working directory
domainname (str or list): Set custom DNS search domains
memswap_limit:

Returns (dict): A dictionary with an image 'Id' key and a 'Warnings' key.

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> container = cli.create_container(image='busybox:latest', command='/bin/sleep 30')
>>> print(container)
{'Id': '8a61192da2b3bb2d922875585e29b74ec0dc4e0117fcbf84c962204e97564cd7',
 'Warnings': None}

diff

Inspect changes on a container's filesystem

Params:

container (str): The container to diff

Returns (str):

execute

c.execute(container, cmd, detach=False, stdout=True, stderr=True,
       stream=False, tty=False)

Execute a command in a running container.

Params:

container (str): can be a container dictionary (result of running inspect_container), unique id or container name.
cmd (str or list): representing the command and its arguments.
detach (bool): flag to True will run the process in the background.
stdout (bool): indicates which output streams to read from.
stderr (bool): indicates which output streams to read from.
stream (bool): indicates whether to return a generator which will yield the streaming response in chunks.

export

Export the contents of a filesystem as a tar archive to STDOUT

Params:

container (str): The container to export

Returns (str): The filesystem tar archive as a str

history

Show the history of an image

Params:

image (str): The image to show history for

Returns (str): The history of the image

images

List images. Identical to the docker images command.

Params:

name (str): Optional filter for a name
quiet (bool): Only show numeric Ids. Returns a list
all (bool): Show all images (by default filter out the intermediate image layers)
viz: Depreciated

Returns (dict or list): A list if quiet=True, otherwise a dict.

[{'Created': 1401926735,
'Id': 'a9eb172552348a9a49180694790b33a1097f546456d041b6e82e4d7716ddb721',
'ParentId': '120e218dd395ec314e7b6249f39d2853911b3d6def6ea164ae05722649f34b16',
'RepoTags': ['busybox:buildroot-2014.02', 'busybox:latest'],
'Size': 0,
'VirtualSize': 2433303},
...

import_image

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.

Params:

src (str or file): Path to tarfile or URL
repository (str): The repository to create
tag (str): The tag to apply
image (str): Use another image like the FROM Dockerfile parameter

info

Display system-wide information. Identical to the docker info command.

Returns (dict): The info as a dict

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.info()
{'Containers': 3,
 'Debug': 1,
 'Driver': 'aufs',
 'DriverStatus': [['Root Dir', '/mnt/sda1/var/lib/docker/aufs'],
  ['Dirs', '225']],
 'ExecutionDriver': 'native-0.2',
 'IPv4Forwarding': 1,
 'Images': 219,
 'IndexServerAddress': 'https://index.docker.io/v1/',
 'InitPath': '/usr/local/bin/docker',
 'InitSha1': '',
 'KernelVersion': '3.16.1-tinycore64',
 'MemoryLimit': 1,
 'NEventsListener': 0,
 'NFd': 11,
 'NGoroutines': 12,
 'OperatingSystem': 'Boot2Docker 1.2.0 (TCL 5.3);',
 'SwapLimit': 1}

insert

DEPRECATED

inspect_container

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

Params:

container (str): The container to inspect

Returns (dict): Nearly the same output as docker inspect, just as a single dict

inspect_image

Identical to the docker inspect command, but only for images

Params:

image_id (str): The image to inspect

Returns (dict): Nearly the same output as docker inspect, just as a single dict

kill

Kill a container or send a signal to a container

Params:

container (str): The container to kill
signal (str or int): The singal to send. Defaults to SIGKILL

login

Nearly identical to the docker login command, but non-interactive.

Params:

username (str): The registry username
password (str): The plaintext password
email (str): The email for the registry account
registry (str): URL to the registry. Ex:https://index.docker.io/v1/
reauth (bool): Whether refresh existing authentication on the docker server.

Returns (dict): The response from the login request

logs

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.

Params:

container (str): The container to get logs from
stdout (bool): Get STDOUT
stderr (bool): Get STDERR
stream (bool): Stream the response
timestamps (bool): Show timestamps

Returns (generator or str):

pause

Pauses all processes within a container.

Params:

container (str): The container to pause

ping

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

Returns (bool)

port

Lookup the public-facing port that is NAT-ed to private_port. Identical to the docker port command.

Params:

container (str): The container to look up
private_port (int): The private port to inspect

Returns (list of dict): The mapping for the host ports

$ docker run -d -p 80:80 ubuntu:14.04 /bin/sleep 30
7174d6347063a83f412fad6124c99cffd25ffe1a0807eb4b7f9cec76ac8cb43b

>>> cli.port('7174d6347063', 80)
[{'HostIp': '0.0.0.0', 'HostPort': '80'}]

pull

Identical to the docker pull command.

Params:

repository (str): The repository to pull
tag (str): The tag to pull
stream (bool): Stream the output as a generator
insecure_registry (bool): Use an insecure registry

Returns (generator or str): The output

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> for line in cli.pull('busybox', stream=True):
...     print(json.dumps(json.loads(line), indent=4))
{
    "status": "Pulling image (latest) from busybox",
    "progressDetail": {},
    "id": "e72ac664f4f0"
}
{
    "status": "Pulling image (latest) from busybox, endpoint: ...",
    "progressDetail": {},
    "id": "e72ac664f4f0"
}

push

Push an image or a repository to the registry. Identical to the docker push command

Params:

repository (str): The repository to push to
tag (str): An optional tag to push
stream (bool): Stream the output as a blocking generator
insecure_registry (bool): Use http:// to connect to the registry

Returns (generator or str): The output of the upload

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> response = [line for line in cli.push('yourname/app', stream=True)]
>>> response
['{"status":"Pushing repository yourname/app (1 tags)"}\\n',
 '{"status":"Pushing","progressDetail":{},"id":"511136ea3c5a"}\\n',
 '{"status":"Image already pushed, skipping","progressDetail":{},
    "id":"511136ea3c5a"}\\n',
 ...
 '{"status":"Pushing tag for rev [918af568e6e5] on {
    https://cdn-registry-1.docker.io/v1/repositories/
    yourname/app/tags/latest}"}\\n']

remove_container

Remove a container. Similar to the docker rm command.

Params:

container (str): The container to remove
v (bool): Remove the volumes associated with the container
link (bool): Remove the specified link and not the underlying container
force (bool): Force the removal of a running container (uses SIGKILL)

remove_image

Remove an image. Similar to the docker rmi command.

Params:

image (str): The image to remove
force (bool): Force removal of the image
noprune (bool): Do not delete untagged parents

restart

Restart a container. Similar to the docker restart command.

If container a dict, the Id key is used.

Params:

container (str or dict): The container to restart
timeout (int): Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default is 10 seconds.

search

Identical to the docker search command.

Params:

term (str): A term to search for

Returns (list of dicts): The response of the search

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> response = cli.search('nginx')
>>> response[:2]
[{'description': 'Official build of Nginx.',
  'is_official': True,
  'is_trusted': False,
  'name': 'nginx',
  'star_count': 266},
 {'description': 'Trusted automated Nginx (http://nginx.org/) ...',
  'is_official': False,
  'is_trusted': True,
  'name': 'dockerfile/nginx',
  'star_count': 60},
  ...

start

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

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

Links 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.

restart_policy is available since v1.2.0 and sets the RestartPolicy for how a container should or should not be restarted on exit. By default the policy is set to no meaning do not restart the container when it exits. The user may specify the restart policy as a dictionary for example:

{
    "MaximumRetryCount": 0,
    "Name": "always"
}

For always restarting the container on exit or can specify to restart the container to restart on failure and can limit number of restarts. For example:

{
    "MaximumRetryCount": 5,
    "Name": "on-failure"
}

cap_add and cap_drop are available since v1.2.0 and can be used to add or drop certain capabilities. The user may specify the capabilities as an array for example:

[
    "SYS_ADMIN",
    "MKNOD"
]

Params:

container (str): The container to start
binds: Volumes to bind
port_bindings (dict): Port bindings. See note above
lxc_conf (dict): LXC config
publish_all_ports (bool): Whether to publish all ports to the host
links (dict or list of tuples): See note above
privileged (bool): Give extended privileges to this container
dns (list): Set custom DNS servers
dns_search (list): DNS search domains
volumes_from (str or list): List of container names or Ids to get volumes from. Optionally a single string joining container id's with commas
network_mode (str): One of ['bridge', None, 'container:<name|id>', 'host']
restart_policy (dict): See note above. "Name" param must be one of ['on-failure', 'always']
cap_add (list of str): See note above
cap_drop (list of str): See note above

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> container = cli.create_container(
...     image='busybox:latest',
...     command='/bin/sleep 30')
>>> response = cli.start(container=container.get('Id'))
>>> print(response)
None

stop

Stops a container. Similar to the docker stop command.

Params:

container (str): The container to stop
timeout (int): Timeout in seconds to wait for the container to stop before sending a SIGKILL

tag

Tag an image into a repository. Identical to the docker tag command.

Params:

image (str): The image to tag
repository (str): The repository to set for the tag
tag (str): The tag name
force (bool): Force

Returns (bool): True if successful

top

Display the running processes of a container

Params:

container (str): The container to inspect

Returns (str): The output of the top

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.create_container('busybox:latest', '/bin/sleep 30', name='sleeper')
>>> cli.start('sleeper')
>>> cli.top('sleeper')
{'Processes': [['952', 'root', '/bin/sleep 30']],
 'Titles': ['PID', 'USER', 'COMMAND']}

unpause

Unpauses all processes within a container.

Params:

container (str): The container to unpause

version

Nearly identical to the docker version command.

Returns (dict): The server version information

>>> from docker import Client
>>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.version()
{
    "KernelVersion": "3.16.4-tinycore64",
    "Arch": "amd64",
    "ApiVersion": "1.15",
    "Version": "1.3.0",
    "GitCommit": "c78088f",
    "Os": "linux",
    "GoVersion": "go1.3.3"
}

wait

Identical to the docker wait command. Block until a container stops, then print its exit code. Returns the value -1 if no StatusCode is returned by the API.

If container a dict, the Id key is used.

Params:

container (str or dict): The container to wait on

Returns (int): The exit code of the container

Files

api.md

Latest commit

History

api.md

File metadata and controls

Client API

attach

build

commit

containers

copy

create_container

diff

execute

export

history

images

import_image

info

insert

inspect_container

inspect_image

kill

login

logs

pause

ping

port

pull

push

remove_container

remove_image

restart

search

start

stop

tag

top

unpause

version

wait