Low-level API

The main object-orientated API is built on top of APIClient. Each method on APIClient maps one-to-one with a REST API endpoint, and returns the response that the API responds with.

It’s possible to use APIClient directly. Some basic things (e.g. running a container) consist of several API calls and are complex to do with the low-level API, but it’s useful if you need extra flexibility and power.

class APIClient(base_url=None, version=None, timeout=60, tls=False, user_agent='docker-sdk-python/2.6.1', num_pools=25)

A low-level client for the Docker Engine API.

Example

>>> import docker
>>> client = docker.APIClient(base_url='unix://var/run/docker.sock')
>>> client.version()
{u'ApiVersion': u'1.24',
 u'Arch': u'amd64',
 u'BuildTime': u'2016-09-27T23:38:15.810178467+00:00',
 u'Experimental': True,
 u'GitCommit': u'45bed2c',
 u'GoVersion': u'go1.6.3',
 u'KernelVersion': u'4.4.22-moby',
 u'Os': u'linux',
 u'Version': u'1.12.2-rc1'}
Parameters:
  • base_url (str) – URL to the Docker server. For example, unix:///var/run/docker.sock or tcp://127.0.0.1:1234.
  • version (str) – The version of the API to use. Set to auto to automatically detect the server’s version. Default: 1.26
  • timeout (int) – Default timeout for API calls, in seconds.
  • tls (bool or TLSConfig) – Enable TLS. Pass True to enable it with default options, or pass a TLSConfig object to use custom configuration.
  • user_agent (str) – Set a custom user agent for requests to the server.

Configs

class ConfigApiMixin
configs(filters=None)

List configs

Parameters:
  • filters (dict) – A map of filters to process on the configs
  • Available filters (list.) – names

Returns (list): A list of configs

create_config(name, data, labels=None)

Create a config

Parameters:
  • name (string) – Name of the config
  • data (bytes) – Config data to be stored
  • labels (dict) – A mapping of labels to assign to the config

Returns (dict): ID of the newly created config

inspect_config(id)

Retrieve config metadata

Parameters:id (string) – Full ID of the config to remove

Returns (dict): A dictionary of metadata

Raises:docker.errors.NotFound – if no config with that ID exists
remove_config(id)

Remove a config

Parameters:id (string) – Full ID of the config to remove

Returns (boolean): True if successful

Raises:docker.errors.NotFound – if no config with that ID exists

Containers

class ContainerApiMixin
attach(container, stdout=True, stderr=True, stream=False, logs=False)

Attach to a container.

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.

Parameters:
  • container (str) – The container to attach to.
  • stdout (bool) – Include stdout.
  • stderr (bool) – Include stderr.
  • stream (bool) – Return container output progressively as an iterator of strings, rather than a single string.
  • logs (bool) – Include the container’s previous output.
Returns:

By default, the container’s output as a single string.

If stream=True, an iterator of output strings.

Raises:

docker.errors.APIError – If the server returns an error.

attach_socket(container, params=None, ws=False)

Like attach, but returns the underlying socket-like object for the HTTP request.

Parameters:
  • container (str) – The container to attach to.
  • params (dict) – Dictionary of request parameters (e.g. stdout, stderr, stream).
  • ws (bool) – Use websockets instead of raw HTTP.
Raises:

docker.errors.APIError – If the server returns an error.

commit(container, repository=None, tag=None, message=None, author=None, changes=None, conf=None)

Commit a container to an image. Similar to the docker commit command.

Parameters:
  • 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
  • changes (str) – Dockerfile instructions to apply while committing
  • conf (dict) – The configuration for the container. See the Engine API documentation for full details.
Raises:

docker.errors.APIError – If the server returns an error.

containers(quiet=False, all=False, trunc=False, latest=False, since=None, before=None, limit=-1, size=False, filters=None)

List containers. Similar to the docker ps command.

Parameters:
  • 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
  • filters (dict) –

    Filters to be processed on the image list. Available filters:

    • exited (int): Only containers with specified exit code
    • status (str): One of restarting, running,
      paused, exited
    • label (str): format either "key" or "key=value"
    • id (str): The id of the container.
    • name (str): The name of the container.
    • ancestor (str): Filter by container ancestor. Format of
      <image-name>[:tag], <image-id>, or <image@digest>.
    • before (str): Only containers created before a particular
      container. Give the container name or id.
    • since (str): Only containers created after a particular
      container. Give container name or id.

    A comprehensive list can be found in the documentation for docker ps.

Returns:

A list of dicts, one per container

Raises:

docker.errors.APIError – If the server returns an error.

copy(container, resource)

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

Deprecated for API version >= 1.20. Use get_archive() instead.

Parameters:
  • container (str) – The container to copy from
  • resource (str) – The path within the container
Returns:

The contents of the file as a string

Raises:

docker.errors.APIError – If the server returns an error.

create_container(image, command=None, hostname=None, user=None, detach=False, stdin_open=False, tty=False, mem_limit=None, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, network_disabled=False, name=None, entrypoint=None, cpu_shares=None, working_dir=None, domainname=None, memswap_limit=None, cpuset=None, host_config=None, mac_address=None, labels=None, volume_driver=None, stop_signal=None, networking_config=None, healthcheck=None, stop_timeout=None, runtime=None)

Creates a container. Parameters are similar to those for the docker run command except it doesn’t support the attach options (-a).

The arguments that are passed directly to this function are host-independent configuration options. Host-specific configuration is passed with the host_config argument. You’ll normally want to use this method in combination with the create_host_config() method to generate host_config.

Port bindings

Port binding is done in two parts: first, provide a list of ports to open inside the container with the ports parameter, then declare bindings with the host_config parameter. For example:

container_id = cli.create_container(
    'busybox', 'ls', ports=[1111, 2222],
    host_config=cli.create_host_config(port_bindings={
        1111: 4567,
        2222: None
    })
)

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

cli.create_host_config(port_bindings={1111: ('127.0.0.1', 4567)})

Or without host port assignment:

cli.create_host_config(port_bindings={1111: ('127.0.0.1',)})

If you wish to use UDP instead of TCP (default), you need to declare ports as such in both the config and host config:

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

To bind multiple host ports to a single container port, use the following syntax:

cli.create_host_config(port_bindings={
    1111: [1234, 4567]
})

You can also bind multiple IPs to a single container port:

cli.create_host_config(port_bindings={
    1111: [
        ('192.168.0.100', 1234),
        ('192.168.0.101', 1234)
    ]
})

Using volumes

Volume declaration is done in two parts. Provide a list of paths to use as mountpoints inside the container with the volumes parameter, and declare mappings from paths on the host in the host_config section.

container_id = cli.create_container(
    'busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'],
    host_config=cli.create_host_config(binds={
        '/home/user1/': {
            'bind': '/mnt/vol2',
            'mode': 'rw',
        },
        '/var/www': {
            'bind': '/mnt/vol1',
            'mode': 'ro',
        }
    })
)

You can alternatively specify binds as a list. This code is equivalent to the example above:

container_id = cli.create_container(
    'busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'],
    host_config=cli.create_host_config(binds=[
        '/home/user1/:/mnt/vol2',
        '/var/www:/mnt/vol1:ro',
    ])
)

Networking

You can specify networks to connect the container to by using the networking_config parameter. At the time of creation, you can only connect a container to a single networking, but you can create more connections by using connect_container_to_network().

For example:

networking_config = docker_client.create_networking_config({
    'network1': docker_client.create_endpoint_config(
        ipv4_address='172.28.0.124',
        aliases=['foo', 'bar'],
        links=['container2']
    )
})

ctnr = docker_client.create_container(
    img, command, networking_config=networking_config
)
Parameters:
  • 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 return 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. 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.
  • 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. Deprecated since API version 1.10. Use host_config instead.
  • volumes (str or list) – List of paths inside the container to use as volumes.
  • volumes_from (list) – List of container names or Ids to get volumes from.
  • network_disabled (bool) – Disable networking
  • name (str) – A name for the container
  • entrypoint (str or list) – An entrypoint
  • working_dir (str) – Path to the working directory
  • domainname (str) – The domain name to use for the container
  • memswap_limit (int) –
  • host_config (dict) – A dictionary created with create_host_config().
  • mac_address (str) – The Mac Address to assign the container
  • labels (dict or list) – A dictionary of name-value labels (e.g. {"label1": "value1", "label2": "value2"}) or a list of names of labels to set with empty values (e.g. ["label1", "label2"])
  • volume_driver (str) – The name of a volume driver/plugin.
  • stop_signal (str) – The stop signal to use to stop the container (e.g. SIGINT).
  • stop_timeout (int) – Timeout to stop the container, in seconds. Default: 10
  • networking_config (dict) – A networking configuration generated by create_networking_config().
  • runtime (str) – Runtime to use with this container.
  • healthcheck (dict) – Specify a test to perform to check that the container is healthy.
Returns:

A dictionary with an image ‘Id’ key and a ‘Warnings’ key.

Raises:
  • docker.errors.ImageNotFound – If the specified image does not exist.
  • docker.errors.APIError – If the server returns an error.
create_container_config(*args, **kwargs)
create_container_from_config(config, name=None)
create_endpoint_config(*args, **kwargs)

Create an endpoint config dictionary to be used with create_networking_config().

Parameters:
  • aliases (list) – A list of aliases for this endpoint. Names in that list can be used within the network to reach the container. Defaults to None.
  • links (list) – A list of links for this endpoint. Containers declared in this list will be linked to this container. Defaults to None.
  • ipv4_address (str) – The IP address of this container on the network, using the IPv4 protocol. Defaults to None.
  • ipv6_address (str) – The IP address of this container on the network, using the IPv6 protocol. Defaults to None.
  • link_local_ips (list) – A list of link-local (IPv4/IPv6) addresses.
Returns:

(dict) An endpoint config.

Example

>>> endpoint_config = client.create_endpoint_config(
    aliases=['web', 'app'],
    links=['app_db'],
    ipv4_address='132.65.0.123'
)
create_host_config(*args, **kwargs)

Create a dictionary for the host_config argument to create_container().

Parameters:
  • auto_remove (bool) – enable auto-removal of the container on daemon side when the container’s process exits.
  • binds (dict) – Volumes to bind. See create_container() for more information.
  • blkio_weight_device – Block IO weight (relative device weight) in the form of: [{"Path": "device_path", "Weight": weight}].
  • blkio_weight – Block IO weight (relative weight), accepts a weight value between 10 and 1000.
  • cap_add (list of str) – Add kernel capabilities. For example, ["SYS_ADMIN", "MKNOD"].
  • cap_drop (list of str) – Drop kernel capabilities.
  • cpu_period (int) – The length of a CPU period in microseconds.
  • cpu_quota (int) – Microseconds of CPU time that the container can get in a CPU period.
  • cpu_shares (int) – CPU shares (relative weight).
  • cpuset_cpus (str) – CPUs in which to allow execution (0-3, 0,1).
  • cpuset_mems (str) – Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
  • device_read_bps – Limit read rate (bytes per second) from a device in the form of: [{“Path”: “device_path”, “Rate”: rate}]
  • device_read_iops – Limit read rate (IO per second) from a device.
  • device_write_bps – Limit write rate (bytes per second) from a device.
  • device_write_iops – Limit write rate (IO per second) from a device.
  • devices (list) –

    Expose host devices to the container, as a list of strings in the form <path_on_host>:<path_in_container>:<cgroup_permissions>.

    For example, /dev/sda:/dev/xvda:rwm allows the container to have read-write access to the host’s /dev/sda via a node named /dev/xvda inside the container.

  • dns (list) – Set custom DNS servers.
  • dns_opt (list) – Additional options to be added to the container’s resolv.conf file
  • dns_search (list) – DNS search domains.
  • extra_hosts (dict) – Addtional hostnames to resolve inside the container, as a mapping of hostname to IP address.
  • group_add (list) – List of additional group names and/or IDs that the container process will run as.
  • init (bool) – Run an init inside the container that forwards signals and reaps processes
  • init_path (str) – Path to the docker-init binary
  • ipc_mode (str) – Set the IPC mode for the container.
  • isolation (str) – Isolation technology to use. Default: None.
  • links (dict or list of tuples) – Either a dictionary mapping name to alias or as a list of (name, alias) tuples.
  • log_config (dict) –

    Logging configuration, as a dictionary with keys:

    • type The logging driver name.
    • config A dictionary of configuration for the logging driver.
  • lxc_conf (dict) – LXC config.
  • mem_limit (float or str) – Memory limit. 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
  • mem_swappiness (int) – Tune a container’s memory swappiness behavior. Accepts number between 0 and 100.
  • memswap_limit (str or int) – Maximum amount of memory + swap a container is allowed to consume.
  • mounts (list) – Specification for mounts to be added to the container. More powerful alternative to binds. Each item in the list is expected to be a docker.types.Mount object.
  • network_mode (str) –

    One of:

    • bridge Create a new network stack for the container on on the bridge network.
    • none No networking for this container.
    • container:<name|id> Reuse another container’s network stack.
    • host Use the host network stack.
  • oom_kill_disable (bool) – Whether to disable OOM killer.
  • oom_score_adj (int) – An integer value containing the score given to the container in order to tune OOM killer preferences.
  • pid_mode (str) – If set to host, use the host PID namespace inside the container.
  • pids_limit (int) – Tune a container’s pids limit. Set -1 for unlimited.
  • port_bindings (dict) – See create_container() for more information.
  • privileged (bool) – Give extended privileges to this container.
  • publish_all_ports (bool) – Publish all ports to the host.
  • read_only (bool) – Mount the container’s root filesystem as read only.
  • restart_policy (dict) –

    Restart the container when it exits. Configured as a dictionary with keys:

    • Name One of on-failure, or always.
    • MaximumRetryCount Number of times to restart the container on failure.
  • security_opt (list) – A list of string values to customize labels for MLS systems, such as SELinux.
  • shm_size (str or int) – Size of /dev/shm (e.g. 1G).
  • storage_opt (dict) – Storage driver options per container as a key-value mapping.
  • sysctls (dict) – Kernel parameters to set in the container.
  • tmpfs (dict) –

    Temporary filesystems to mount, as a dictionary mapping a path inside the container to options for that path.

    For example:

    {
        '/mnt/vol2': '',
        '/mnt/vol1': 'size=3G,uid=1000'
    }
    
  • ulimits (list) – Ulimits to set inside the container, as a list of dicts.
  • userns_mode (str) – Sets the user namespace mode for the container when user namespace remapping option is enabled. Supported values are: host
  • volumes_from (list) – List of container names or IDs to get volumes from.
  • runtime (str) – Runtime to use with this container.
Returns:

(dict) A dictionary which can be passed to the host_config argument to create_container().

Example

>>> cli.create_host_config(privileged=True, cap_drop=['MKNOD'],
                           volumes_from=['nostalgic_newton'])
{'CapDrop': ['MKNOD'], 'LxcConf': None, 'Privileged': True,
 'VolumesFrom': ['nostalgic_newton'], 'PublishAllPorts': False}
create_networking_config(*args, **kwargs)

Create a networking config dictionary to be used as the networking_config parameter in create_container().

Parameters:endpoints_config (dict) – A dictionary mapping network names to endpoint configurations generated by create_endpoint_config().
Returns:(dict) A networking config.

Example

>>> docker_client.create_network('network1')
>>> networking_config = docker_client.create_networking_config({
    'network1': docker_client.create_endpoint_config()
})
>>> container = docker_client.create_container(
    img, command, networking_config=networking_config
)
diff(container)

Inspect changes on a container’s filesystem.

Parameters:container (str) – The container to diff
Returns:(str)
Raises:docker.errors.APIError – If the server returns an error.
export(container)

Export the contents of a filesystem as a tar archive.

Parameters:container (str) – The container to export
Returns:The filesystem tar archive
Return type:(str)
Raises:docker.errors.APIError – If the server returns an error.
get_archive(container, path)

Retrieve a file or folder from a container in the form of a tar archive.

Parameters:
  • container (str) – The container where the file is located
  • path (str) – Path to the file or folder to retrieve
Returns:

First element is a raw tar data stream. Second element is a dict containing stat information on the specified path.

Return type:

(tuple)

Raises:

docker.errors.APIError – If the server returns an error.

inspect_container(container)

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

Parameters:container (str) – The container to inspect
Returns:Similar to the output of docker inspect, but as a single dict
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
kill(container, signal=None)

Kill a container or send a signal to a container.

Parameters:
  • container (str) – The container to kill
  • signal (str or int) – The signal to send. Defaults to SIGKILL
Raises:

docker.errors.APIError – If the server returns an error.

logs(container, stdout=True, stderr=True, stream=False, timestamps=False, tail='all', since=None, follow=None)

Get logs from a container. Similar 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.

Parameters:
  • 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
  • tail (str or int) – Output specified number of lines at the end of logs. Either an integer of number of lines or the string all. Default all
  • since (datetime or int) – Show logs since a given datetime or integer epoch (in seconds)
  • follow (bool) – Follow log output
Returns:

(generator or str)

Raises:

docker.errors.APIError – If the server returns an error.

pause(container)

Pauses all processes within a container.

Parameters:container (str) – The container to pause
Raises:docker.errors.APIError – If the server returns an error.
port(container, private_port)

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

Parameters:
  • container (str) – The container to look up
  • private_port (int) – The private port to inspect
Returns:

The mapping for the host ports

Return type:

(list of dict)

Raises:

docker.errors.APIError – If the server returns an error.

Example

$ docker run -d -p 80:80 ubuntu:14.04 /bin/sleep 30
7174d6347063a83f412fad6124c99cffd25ffe1a0807eb4b7f9cec76ac8cb43b
>>> cli.port('7174d6347063', 80)
[{'HostIp': '0.0.0.0', 'HostPort': '80'}]
prune_containers(filters=None)

Delete stopped containers

Parameters:filters (dict) – Filters to process on the prune list.
Returns:
A dict containing a list of deleted container IDs and
the amount of disk space reclaimed in bytes.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
put_archive(container, path, data)

Insert a file or folder in an existing container using a tar archive as source.

Parameters:
  • container (str) – The container where the file(s) will be extracted
  • path (str) – Path inside the container where the file(s) will be extracted. Must exist.
  • data (bytes) – tar data to be extracted
Returns:

True if the call succeeds.

Return type:

(bool)

Raises:

docker.errors.APIError – If the server returns an error.

remove_container(container, v=False, link=False, force=False)

Remove a container. Similar to the docker rm command.

Parameters:
  • 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)
Raises:

docker.errors.APIError – If the server returns an error.

rename(container, name)

Rename a container. Similar to the docker rename command.

Parameters:
  • container (str) – ID of the container to rename
  • name (str) – New name for the container
Raises:

docker.errors.APIError – If the server returns an error.

resize(container, height, width)

Resize the tty session.

Parameters:
  • container (str or dict) – The container to resize
  • height (int) – Height of tty session
  • width (int) – Width of tty session
Raises:

docker.errors.APIError – If the server returns an error.

restart(container, timeout=10)

Restart a container. Similar to the docker restart command.

Parameters:
  • container (str or dict) – The container to restart. If a dict, the Id key is used.
  • 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.
Raises:

docker.errors.APIError – If the server returns an error.

start(container, *args, **kwargs)

Start a container. Similar to the docker start command, but doesn’t support attach options.

Deprecation warning: Passing configuration options in start is no longer supported. Users are expected to provide host config options in the host_config parameter of create_container().

Parameters:

container (str) – The container to start

Raises:
  • docker.errors.APIError – If the server returns an error.
  • docker.errors.DeprecatedMethod – If any argument besides container are provided.

Example

>>> container = cli.create_container(
...     image='busybox:latest',
...     command='/bin/sleep 30')
>>> cli.start(container=container.get('Id'))
stats(container, decode=None, stream=True)

Stream statistics for a specific container. Similar to the docker stats command.

Parameters:
  • container (str) – The container to stream statistics from
  • decode (bool) – If set to true, stream will be decoded into dicts on the fly. False by default.
  • stream (bool) – If set to false, only the current stats will be returned instead of a stream. True by default.
Raises:

docker.errors.APIError – If the server returns an error.

stop(container, timeout=10)

Stops a container. Similar to the docker stop command.

Parameters:
  • container (str) – The container to stop
  • timeout (int) – Timeout in seconds to wait for the container to stop before sending a SIGKILL. Default: 10
Raises:

docker.errors.APIError – If the server returns an error.

top(container, ps_args=None)

Display the running processes of a container.

Parameters:
  • container (str) – The container to inspect
  • ps_args (str) – An optional arguments passed to ps (e.g. aux)
Returns:

The output of the top

Return type:

(str)

Raises:

docker.errors.APIError – If the server returns an error.

unpause(container)

Unpause all processes within a container.

Parameters:container (str) – The container to unpause
update_container(container, blkio_weight=None, cpu_period=None, cpu_quota=None, cpu_shares=None, cpuset_cpus=None, cpuset_mems=None, mem_limit=None, mem_reservation=None, memswap_limit=None, kernel_memory=None, restart_policy=None)

Update resource configs of one or more containers.

Parameters:
  • container (str) – The container to inspect
  • blkio_weight (int) – Block IO (relative weight), between 10 and 1000
  • cpu_period (int) – Limit CPU CFS (Completely Fair Scheduler) period
  • cpu_quota (int) – Limit CPU CFS (Completely Fair Scheduler) quota
  • cpu_shares (int) – CPU shares (relative weight)
  • cpuset_cpus (str) – CPUs in which to allow execution
  • cpuset_mems (str) – MEMs in which to allow execution
  • mem_limit (int or str) – Memory limit
  • mem_reservation (int or str) – Memory soft limit
  • memswap_limit (int or str) – Total memory (memory + swap), -1 to disable swap
  • kernel_memory (int or str) – Kernel memory limit
  • restart_policy (dict) – Restart policy dictionary
Returns:

Dictionary containing a Warnings key.

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

wait(container, timeout=None)

Block until a container stops, then return its exit code. Similar to the docker wait command.

Parameters:
  • container (str or dict) – The container to wait on. If a dict, the Id key is used.
  • timeout (int) – Request timeout
Returns:

The exit code of the container. Returns -1 if the API responds without a StatusCode attribute.

Return type:

(int)

Raises:
  • requests.exceptions.ReadTimeout – If the timeout is exceeded.
  • docker.errors.APIError – If the server returns an error.

Images

class ImageApiMixin
get_image(image)

Get a tarball of an image. Similar to the docker save command.

Parameters:image (str) – Image name to get
Returns:The response from the daemon.
Return type:(urllib3.response.HTTPResponse object)
Raises:docker.errors.APIError – If the server returns an error.

Example

>>> image = cli.get_image("fedora:latest")
>>> f = open('/tmp/fedora-latest.tar', 'w')
>>> f.write(image.data)
>>> f.close()
history(image)

Show the history of an image.

Parameters:image (str) – The image to show history for
Returns:The history of the image
Return type:(str)
Raises:docker.errors.APIError – If the server returns an error.
images(name=None, quiet=False, all=False, viz=False, filters=None)

List images. Similar to the docker images command.

Parameters:
  • name (str) – Only show images belonging to the repository name
  • quiet (bool) – Only return numeric IDs as a list.
  • all (bool) – Show intermediate image layers. By default, these are filtered out.
  • filters (dict) – Filters to be processed on the image list. Available filters: - dangling (bool) - label (str): format either key or key=value
Returns:

A list if quiet=True, otherwise a dict.

Return type:

(dict or list)

Raises:

docker.errors.APIError – If the server returns an error.

import_image(src=None, repository=None, tag=None, image=None, changes=None, stream_src=False)

Import an image. Similar to the docker import command.

If src is a string or unicode string, it will first be treated as a path to a tarball on the local system. If there is an error reading from that file, src will be treated as a URL instead to fetch the image from. You can also pass an open file handle as src, in which case the data will be read from that file.

If src is unset but image is set, the image parameter will be taken as the name of an existing image to import from.

Parameters:
  • src (str or file) – Path to tarfile, URL, or file-like object
  • repository (str) – The repository to create
  • tag (str) – The tag to apply
  • image (str) – Use another image like the FROM Dockerfile parameter
import_image_from_data(data, repository=None, tag=None, changes=None)

Like import_image(), but allows importing in-memory bytes data.

Parameters:
  • data (bytes collection) – Bytes collection containing valid tar data
  • repository (str) – The repository to create
  • tag (str) – The tag to apply
import_image_from_file(filename, repository=None, tag=None, changes=None)

Like import_image(), but only supports importing from a tar file on disk.

Parameters:
  • filename (str) – Full path to a tar file.
  • repository (str) – The repository to create
  • tag (str) – The tag to apply
Raises:

IOError – File does not exist.

import_image_from_image(image, repository=None, tag=None, changes=None)

Like import_image(), but only supports importing from another image, like the FROM Dockerfile parameter.

Parameters:
  • image (str) – Image name to import from
  • repository (str) – The repository to create
  • tag (str) – The tag to apply
import_image_from_stream(stream, repository=None, tag=None, changes=None)
import_image_from_url(url, repository=None, tag=None, changes=None)

Like import_image(), but only supports importing from a URL.

Parameters:
  • url (str) – A URL pointing to a tar file.
  • repository (str) – The repository to create
  • tag (str) – The tag to apply
insert(image, url, path)
inspect_image(image)

Get detailed information about an image. Similar to the docker inspect command, but only for images.

Parameters:image (str) – The image to inspect
Returns:Similar to the output of docker inspect, but as a
Return type:(dict)

single dict

Raises:docker.errors.APIError – If the server returns an error.
load_image(data, quiet=None)

Load an image that was previously saved using get_image() (or docker save). Similar to docker load.

Parameters:
  • data (binary) – Image data to be loaded.
  • quiet (boolean) – Suppress progress details in response.
Returns:

Progress output as JSON objects. Only available for

API version >= 1.23

Return type:

(generator)

Raises:

docker.errors.APIError – If the server returns an error.

prune_images(filters=None)

Delete unused images

Parameters:filters (dict) – Filters to process on the prune list. Available filters: - dangling (bool): When set to true (or 1), prune only unused and untagged images.
Returns:
A dict containing a list of deleted image IDs and
the amount of disk space reclaimed in bytes.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
pull(repository, tag=None, stream=False, insecure_registry=False, auth_config=None, decode=False)

Pulls an image. Similar to the docker pull command.

Parameters:
  • 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
  • auth_config (dict) – Override the credentials that login() has set for this request. auth_config should contain the username and password keys to be valid.
Returns:

The output

Return type:

(generator or str)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> 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(repository, tag=None, stream=False, insecure_registry=False, auth_config=None, decode=False)

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

Parameters:
  • 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
  • auth_config (dict) – Override the credentials that login() has set for this request. auth_config should contain the username and password keys to be valid.
Returns:

The output from the server.

Return type:

(generator or str)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> for line in cli.push('yourname/app', stream=True):
...   print line
{"status":"Pushing repository yourname/app (1 tags)"}
{"status":"Pushing","progressDetail":{},"id":"511136ea3c5a"}
{"status":"Image already pushed, skipping","progressDetail":{},
 "id":"511136ea3c5a"}
...
remove_image(image, force=False, noprune=False)

Remove an image. Similar to the docker rmi command.

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

Search for images on Docker Hub. Similar to the docker search command.

Parameters:term (str) – A term to search for.
Returns:The response of the search.
Return type:(list of dicts)
Raises:docker.errors.APIError – If the server returns an error.
tag(image, repository, tag=None, force=False)

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

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

True if successful

Return type:

(bool)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> client.tag('ubuntu', 'localhost:5000/ubuntu', 'latest',
               force=True)

Building images

class BuildApiMixin
build(path=None, tag=None, quiet=False, fileobj=None, nocache=False, rm=False, stream=False, timeout=None, custom_context=False, encoding=None, pull=False, forcerm=False, dockerfile=None, container_limits=None, decode=False, buildargs=None, gzip=False, shmsize=None, labels=None, cache_from=None, target=None, network_mode=None, squash=None, extra_hosts=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).

Example

>>> from io import BytesIO
>>> from docker import APIClient
>>> dockerfile = '''
... # Shared Volume
... FROM busybox:buildroot-2014.02
... VOLUME /data
... CMD ["/bin/sh"]
... '''
>>> f = BytesIO(dockerfile.encode('utf-8'))
>>> cli = APIClient(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 : VOLUME /data\n"}',
 '{"stream":" ---\u003e Running in abdc1e6896c6\n"}',
 '{"stream":" ---\u003e 713bca62012e\n"}',
 '{"stream":"Removing intermediate container abdc1e6896c6\n"}',
 '{"stream":"Step 2 : 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"}']
Parameters:
  • path (str) – Path to the directory containing the Dockerfile
  • fileobj – A file object to use as the Dockerfile. (Or a file-like object)
  • tag (str) – A tag to add to the final image
  • quiet (bool) – Whether to return the status
  • nocache (bool) – Don’t use the cache when set to True
  • rm (bool) – Remove intermediate containers. The docker build command now defaults to --rm=true, but we have kept the old default of False to preserve backward compatibility
  • stream (bool) – Deprecated for API version > 1.8 (always True). 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
  • forcerm (bool) – Always remove intermediate containers, even after unsuccessful builds
  • dockerfile (str) – path within the build context to the Dockerfile
  • buildargs (dict) – A dictionary of build arguments
  • container_limits (dict) –

    A dictionary of limits applied to each container created by the build process. Valid keys:

    • memory (int): set memory limit for build
    • memswap (int): Total memory (memory + swap), -1 to disable
      swap
    • cpushares (int): CPU shares (relative weight)
    • cpusetcpus (str): CPUs in which to allow execution, e.g.,
      "0-3", "0,1"
  • decode (bool) – If set to True, the returned stream will be decoded into dicts on the fly. Default False
  • shmsize (int) – Size of /dev/shm in bytes. The size must be greater than 0. If omitted the system uses 64MB
  • labels (dict) – A dictionary of labels to set on the image
  • cache_from (list) – A list of images used for build cache resolution
  • target (str) – Name of the build-stage to build in a multi-stage Dockerfile
  • network_mode (str) – networking mode for the run commands during build
  • squash (bool) – Squash the resulting images layers into a single layer.
  • extra_hosts (dict) – Extra hosts to add to /etc/hosts in building containers, as a mapping of hostname to IP address.
Returns:

A generator for the build output.

Raises:
  • docker.errors.APIError – If the server returns an error.
  • TypeError – If neither path nor fileobj is specified.

Networks

class NetworkApiMixin
connect_container_to_network(container, net_id, ipv4_address=None, ipv6_address=None, aliases=None, links=None, link_local_ips=None)

Connect a container to a network.

Parameters:
  • container (str) – container-id/name to be connected to the network
  • net_id (str) – network id
  • aliases (list) – A list of aliases for this endpoint. Names in that list can be used within the network to reach the container. Defaults to None.
  • links (list) – A list of links for this endpoint. Containers declared in this list will be linked to this container. Defaults to None.
  • ipv4_address (str) – The IP address of this container on the network, using the IPv4 protocol. Defaults to None.
  • ipv6_address (str) – The IP address of this container on the network, using the IPv6 protocol. Defaults to None.
  • link_local_ips (list) – A list of link-local (IPv4/IPv6) addresses.
create_network(name, driver=None, options=None, ipam=None, check_duplicate=None, internal=False, labels=None, enable_ipv6=False, attachable=None, scope=None, ingress=None)

Create a network. Similar to the docker network create.

Parameters:
  • name (str) – Name of the network
  • driver (str) – Name of the driver used to create the network
  • options (dict) – Driver options as a key-value dictionary
  • ipam (IPAMConfig) – Optional custom IP scheme for the network.
  • check_duplicate (bool) – Request daemon to check for networks with same name. Default: None.
  • internal (bool) – Restrict external access to the network. Default False.
  • labels (dict) – Map of labels to set on the network. Default None.
  • enable_ipv6 (bool) – Enable IPv6 on the network. Default False.
  • attachable (bool) – If enabled, and the network is in the global scope, non-service containers on worker nodes will be able to connect to the network.
  • scope (str) – Specify the network’s scope (local, global or swarm)
  • ingress (bool) – If set, create an ingress network which provides the routing-mesh in swarm mode.
Returns:

The created network reference object

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

Example

A network using the bridge driver:

>>> client.create_network("network1", driver="bridge")

You can also create more advanced networks with custom IPAM configurations. For example, setting the subnet to 192.168.52.0/24 and gateway address to 192.168.52.254.

>>> ipam_pool = docker.types.IPAMPool(
    subnet='192.168.52.0/24',
    gateway='192.168.52.254'
)
>>> ipam_config = docker.types.IPAMConfig(
    pool_configs=[ipam_pool]
)
>>> docker_client.create_network("network1", driver="bridge",
                                 ipam=ipam_config)
disconnect_container_from_network(container, net_id, force=False)

Disconnect a container from a network.

Parameters:
  • container (str) – container ID or name to be disconnected from the network
  • net_id (str) – network ID
  • force (bool) – Force the container to disconnect from a network. Default: False
inspect_network(net_id, verbose=None, scope=None)

Get detailed information about a network.

Parameters:
  • net_id (str) – ID of network
  • verbose (bool) – Show the service details across the cluster in swarm mode.
  • scope (str) – Filter the network by scope (swarm, global or local).
networks(names=None, ids=None, filters=None)

List networks. Similar to the docker networks ls command.

Parameters:
  • names (list) – List of names to filter by
  • ids (list) – List of ids to filter by
  • filters (dict) – Filters to be processed on the network list. Available filters: - driver=[<driver-name>] Matches a network’s driver. - label=[<key>] or label=[<key>=<value>]. - type=["custom"|"builtin"] Filters networks by type.
Returns:

List of network objects.

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

prune_networks(filters=None)

Delete unused networks

Parameters:filters (dict) – Filters to process on the prune list.
Returns:
A dict containing a list of deleted network names and
the amount of disk space reclaimed in bytes.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
remove_network(net_id)

Remove a network. Similar to the docker network rm command.

Parameters:net_id (str) – The network’s id

Volumes

class VolumeApiMixin
create_volume(name=None, driver=None, driver_opts=None, labels=None)

Create and register a named volume

Parameters:
  • name (str) – Name of the volume
  • driver (str) – Name of the driver used to create the volume
  • driver_opts (dict) – Driver options as a key-value dictionary
  • labels (dict) – Labels to set on the volume
Returns:

The created volume reference object

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> volume = cli.create_volume(name='foobar', driver='local',
        driver_opts={'foo': 'bar', 'baz': 'false'},
        labels={"key": "value"})
>>> print(volume)
{u'Driver': u'local',
 u'Labels': {u'key': u'value'},
 u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
 u'Name': u'foobar',
 u'Scope': u'local'}
inspect_volume(name)

Retrieve volume info by name.

Parameters:name (str) – volume name
Returns:Volume information dictionary
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.

Example

>>> cli.inspect_volume('foobar')
{u'Driver': u'local',
 u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
 u'Name': u'foobar'}
prune_volumes(filters=None)

Delete unused volumes

Parameters:filters (dict) – Filters to process on the prune list.
Returns:
A dict containing a list of deleted volume names and
the amount of disk space reclaimed in bytes.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
remove_volume(name, force=False)

Remove a volume. Similar to the docker volume rm command.

Parameters:
  • name (str) – The volume’s name
  • force (bool) – Force removal of volumes that were already removed out of band by the volume driver plugin.
Raises:

docker.errors.APIError – If volume failed to remove.

volumes(filters=None)

List volumes currently registered by the docker daemon. Similar to the docker volume ls command.

Parameters:filters (dict) – Server-side list filtering options.
Returns:Dictionary with list of volume objects as value of the Volumes key.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.

Example

>>> cli.volumes()
{u'Volumes': [{u'Driver': u'local',
   u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
   u'Name': u'foobar'},
  {u'Driver': u'local',
   u'Mountpoint': u'/var/lib/docker/volumes/baz/_data',
   u'Name': u'baz'}]}

Executing commands in containers

class ExecApiMixin
exec_create(container, cmd, stdout=True, stderr=True, stdin=False, tty=False, privileged=False, user='', environment=None)

Sets up an exec instance in a running container.

Parameters:
  • container (str) – Target container where exec instance will be created
  • cmd (str or list) – Command to be executed
  • stdout (bool) – Attach to stdout. Default: True
  • stderr (bool) – Attach to stderr. Default: True
  • stdin (bool) – Attach to stdin. Default: False
  • tty (bool) – Allocate a pseudo-TTY. Default: False
  • privileged (bool) – Run as privileged.
  • user (str) – User to execute command as. Default: root
  • environment (dict or list) – A dictionary or a list of strings in the following format ["PASSWORD=xxx"] or {"PASSWORD": "xxx"}.
Returns:

A dictionary with an exec Id key.

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

exec_inspect(exec_id)

Return low-level information about an exec command.

Parameters:exec_id (str) – ID of the exec instance
Returns:Dictionary of values returned by the endpoint.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
exec_resize(exec_id, height=None, width=None)

Resize the tty session used by the specified exec command.

Parameters:
  • exec_id (str) – ID of the exec instance
  • height (int) – Height of tty session
  • width (int) – Width of tty session
exec_start(exec_id, detach=False, tty=False, stream=False, socket=False)

Start a previously set up exec instance.

Parameters:
  • exec_id (str) – ID of the exec instance
  • detach (bool) – If true, detach from the exec command. Default: False
  • tty (bool) – Allocate a pseudo-TTY. Default: False
  • stream (bool) – Stream response data. Default: False
  • socket (bool) – Return the connection socket to allow custom read/write operations.
Returns:

If stream=True, a generator yielding response chunks. If socket=True, a socket object for the connection. A string containing response data otherwise.

Return type:

(generator or str)

Raises:

docker.errors.APIError – If the server returns an error.

Swarms

class SwarmApiMixin
create_swarm_spec(*args, **kwargs)

Create a docker.types.SwarmSpec instance that can be used as the swarm_spec argument in init_swarm().

Parameters:
  • task_history_retention_limit (int) – Maximum number of tasks history stored.
  • snapshot_interval (int) – Number of logs entries between snapshot.
  • keep_old_snapshots (int) – Number of snapshots to keep beyond the current snapshot.
  • log_entries_for_slow_followers (int) – Number of log entries to keep around to sync up slow followers after a snapshot is created.
  • heartbeat_tick (int) – Amount of ticks (in seconds) between each heartbeat.
  • election_tick (int) – Amount of ticks (in seconds) needed without a leader to trigger a new election.
  • dispatcher_heartbeat_period (int) – The delay for an agent to send a heartbeat to the dispatcher.
  • node_cert_expiry (int) – Automatic expiry for nodes certificates.
  • external_cas (list) – Configuration for forwarding signing requests to an external certificate authority. Use a list of docker.types.SwarmExternalCA.
  • name (string) – Swarm’s name
  • labels (dict) – User-defined key/value metadata.
  • signing_ca_cert (str) – The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
  • signing_ca_key (str) – The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
  • ca_force_rotate (int) – An integer whose purpose is to force swarm to generate a new signing CA certificate and key, if none have been specified.
  • autolock_managers (boolean) – If set, generate a key and use it to lock data stored on the managers.
  • log_driver (DriverConfig) – The default log driver to use for tasks created in the orchestrator.
Returns:

docker.types.SwarmSpec

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> spec = client.create_swarm_spec(
  snapshot_interval=5000, log_entries_for_slow_followers=1200
)
>>> client.init_swarm(
  advertise_addr='eth0', listen_addr='0.0.0.0:5000',
  force_new_cluster=False, swarm_spec=spec
)
init_swarm(advertise_addr=None, listen_addr='0.0.0.0:2377', force_new_cluster=False, swarm_spec=None)

Initialize a new Swarm using the current connected engine as the first node.

Parameters:
  • advertise_addr (string) – Externally reachable address advertised to other nodes. This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the port number from the listen address is used. If advertise_addr is not specified, it will be automatically detected when possible. Default: None
  • listen_addr (string) – Listen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the default swarm listening port is used. Default: ‘0.0.0.0:2377’
  • force_new_cluster (bool) – Force creating a new Swarm, even if already part of one. Default: False
  • swarm_spec (dict) – Configuration settings of the new Swarm. Use APIClient.create_swarm_spec to generate a valid configuration. Default: None
Returns:

True if successful.

Raises:

docker.errors.APIError – If the server returns an error.

inspect_node(node_id)

Retrieve low-level information about a swarm node

Parameters:node_id (string) – ID of the node to be inspected.
Returns:A dictionary containing data about this node.
Raises:docker.errors.APIError – If the server returns an error.
inspect_swarm()

Retrieve low-level information about the current swarm.

Returns:A dictionary containing data about the swarm.
Raises:docker.errors.APIError – If the server returns an error.
join_swarm(remote_addrs, join_token, listen_addr=None, advertise_addr=None)

Make this Engine join a swarm that has already been created.

Parameters:
  • remote_addrs (list) – Addresses of one or more manager nodes already participating in the Swarm to join.
  • join_token (string) – Secret token for joining this Swarm.
  • listen_addr (string) – Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). Default: None
  • advertise_addr (string) – Externally reachable address advertised to other nodes. This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the port number from the listen address is used. If AdvertiseAddr is not specified, it will be automatically detected when possible. Default: None
Returns:

True if the request went through.

Raises:

docker.errors.APIError – If the server returns an error.

leave_swarm(force=False)

Leave a swarm.

Parameters:force (bool) – Leave the swarm even if this node is a manager. Default: False
Returns:True if the request went through.
Raises:docker.errors.APIError – If the server returns an error.
nodes(filters=None)

List swarm nodes.

Parameters:filters (dict) – Filters to process on the nodes list. Valid filters: id, name, membership and role. Default: None
Returns:A list of dictionaries containing data about each swarm node.
Raises:docker.errors.APIError – If the server returns an error.
remove_node(node_id, force=False)

Remove a node from the swarm.

Parameters:
  • node_id (string) – ID of the node to be removed.
  • force (bool) – Force remove an active node. Default: False
Raises:
  • docker.errors.NotFound – If the node referenced doesn’t exist in the swarm.
  • docker.errors.APIError – If the server returns an error.
Returns:

True if the request was successful.

update_node(node_id, version, node_spec=None)

Update the Node’s configuration

Parameters:
  • node_id (string) – ID of the node to be updated.
  • version (int) – The version number of the node object being updated. This is required to avoid conflicting writes.
  • node_spec (dict) – Configuration settings to update. Any values not provided will be removed. Default: None
Returns:

True if the request went through.

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> node_spec = {'Availability': 'active',
             'Name': 'node-name',
             'Role': 'manager',
             'Labels': {'foo': 'bar'}
            }
>>> client.update_node(node_id='24ifsmvkjbyhk', version=8,
    node_spec=node_spec)
update_swarm(version, swarm_spec=None, rotate_worker_token=False, rotate_manager_token=False)

Update the Swarm’s configuration

Parameters:
  • version (int) – The version number of the swarm object being updated. This is required to avoid conflicting writes.
  • swarm_spec (dict) – Configuration settings to update. Use create_swarm_spec() to generate a valid configuration. Default: None.
  • rotate_worker_token (bool) – Rotate the worker join token. Default: False.
  • rotate_manager_token (bool) – Rotate the manager join token. Default: False.
Returns:

True if the request went through.

Raises:

docker.errors.APIError – If the server returns an error.

Services

class ServiceApiMixin
create_service(task_template, name=None, labels=None, mode=None, update_config=None, networks=None, endpoint_config=None, endpoint_spec=None)

Create a service.

Parameters:
  • task_template (TaskTemplate) – Specification of the task to start as part of the new service.
  • name (string) – User-defined name for the service. Optional.
  • labels (dict) – A map of labels to associate with the service. Optional.
  • mode (ServiceMode) – Scheduling mode for the service (replicated or global). Defaults to replicated.
  • update_config (UpdateConfig) – Specification for the update strategy of the service. Default: None
  • networks (list) – List of network names or IDs to attach the service to. Default: None.
  • endpoint_spec (EndpointSpec) – Properties that can be configured to access and load balance a service. Default: None.
Returns:

A dictionary containing an ID key for the newly created service.

Raises:

docker.errors.APIError – If the server returns an error.

inspect_service(service, insert_defaults=None)

Return information about a service.

Parameters:
  • service (str) – Service name or ID.
  • insert_defaults (boolean) – If true, default values will be merged into the service inspect output.
Returns:

True if successful.

Raises:

docker.errors.APIError – If the server returns an error.

inspect_task(task)

Retrieve information about a task.

Parameters:task (str) – Task ID
Returns:Information about the task.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
remove_service(service)

Stop and remove a service.

Parameters:service (str) – Service name or ID
Returns:True if successful.
Raises:docker.errors.APIError – If the server returns an error.
service_logs(service, details=False, follow=False, stdout=False, stderr=False, since=0, timestamps=False, tail='all', is_tty=None)

Get log stream for a service. Note: This endpoint works only for services with the json-file or journald logging drivers.

Parameters:
  • service (str) – ID or name of the service
  • details (bool) – Show extra details provided to logs. Default: False
  • follow (bool) – Keep connection open to read logs as they are sent by the Engine. Default: False
  • stdout (bool) – Return logs from stdout. Default: False
  • stderr (bool) – Return logs from stderr. Default: False
  • since (int) – UNIX timestamp for the logs staring point. Default: 0
  • timestamps (bool) – Add timestamps to every log line.
  • tail (string or int) – Number of log lines to be returned, counting from the current end of the logs. Specify an integer or 'all' to output all log lines. Default: all
  • is_tty (bool) – Whether the service’s ContainerSpec enables the TTY option. If omitted, the method will query the Engine for the information, causing an additional roundtrip.

Returns (generator): Logs for the service.

services(filters=None)

List services.

Parameters:filters (dict) – Filters to process on the nodes list. Valid filters: id, name , label and mode. Default: None.
Returns:A list of dictionaries containing data about each service.
Raises:docker.errors.APIError – If the server returns an error.
tasks(filters=None)

Retrieve a list of tasks.

Parameters:filters (dict) – A map of filters to process on the tasks list. Valid filters: id, name, service, node, label and desired-state.
Returns:List of task dictionaries.
Return type:(list)
Raises:docker.errors.APIError – If the server returns an error.
update_service(service, version, task_template=None, name=None, labels=None, mode=None, update_config=None, networks=None, endpoint_config=None, endpoint_spec=None)

Update a service.

Parameters:
  • service (string) – A service identifier (either its name or service ID).
  • version (int) – The version number of the service object being updated. This is required to avoid conflicting writes.
  • task_template (TaskTemplate) – Specification of the updated task to start as part of the service.
  • name (string) – New name for the service. Optional.
  • labels (dict) – A map of labels to associate with the service. Optional.
  • mode (ServiceMode) – Scheduling mode for the service (replicated or global). Defaults to replicated.
  • update_config (UpdateConfig) – Specification for the update strategy of the service. Default: None.
  • networks (list) – List of network names or IDs to attach the service to. Default: None.
  • endpoint_spec (EndpointSpec) – Properties that can be configured to access and load balance a service. Default: None.
Returns:

True if successful.

Raises:

docker.errors.APIError – If the server returns an error.

Plugins

class PluginApiMixin
configure_plugin(name, options)

Configure a plugin.

Parameters:
  • name (string) – The name of the plugin. The :latest tag is optional, and is the default if omitted.
  • options (dict) – A key-value mapping of options
Returns:

True if successful

create_plugin(name, plugin_data_dir, gzip=False)

Create a new plugin.

Parameters:
  • name (string) – The name of the plugin. The :latest tag is optional, and is the default if omitted.
  • plugin_data_dir (string) – Path to the plugin data directory. Plugin data directory must contain the config.json manifest file and the rootfs directory.
  • gzip (bool) – Compress the context using gzip. Default: False
Returns:

True if successful

disable_plugin(name)

Disable an installed plugin.

Parameters:name (string) – The name of the plugin. The :latest tag is optional, and is the default if omitted.
Returns:True if successful
enable_plugin(name, timeout=0)

Enable an installed plugin.

Parameters:
  • name (string) – The name of the plugin. The :latest tag is optional, and is the default if omitted.
  • timeout (int) – Operation timeout (in seconds). Default: 0
Returns:

True if successful

inspect_plugin(name)

Retrieve plugin metadata.

Parameters:name (string) – The name of the plugin. The :latest tag is optional, and is the default if omitted.
Returns:A dict containing plugin info
plugin_privileges(name)

Retrieve list of privileges to be granted to a plugin.

Parameters:name (string) – Name of the remote plugin to examine. The :latest tag is optional, and is the default if omitted.
Returns:A list of dictionaries representing the plugin’s permissions
plugins()

Retrieve a list of installed plugins.

Returns:A list of dicts, one per plugin
pull_plugin(remote, privileges, name=None)

Pull and install a plugin. After the plugin is installed, it can be enabled using enable_plugin().

Parameters:
  • remote (string) – Remote reference for the plugin to install. The :latest tag is optional, and is the default if omitted.
  • privileges (list) – A list of privileges the user consents to grant to the plugin. Can be retrieved using plugin_privileges().
  • name (string) – Local name for the pulled plugin. The :latest tag is optional, and is the default if omitted.
Returns:

An iterable object streaming the decoded API logs

push_plugin(name)

Push a plugin to the registry.

Parameters:name (string) – Name of the plugin to upload. The :latest tag is optional, and is the default if omitted.
Returns:True if successful
remove_plugin(name, force=False)

Remove an installed plugin.

Parameters:
  • name (string) – Name of the plugin to remove. The :latest tag is optional, and is the default if omitted.
  • force (bool) – Disable the plugin before removing. This may result in issues if the plugin is in use by a container.
Returns:

True if successful

upgrade_plugin(name, remote, privileges)

Upgrade an installed plugin.

Parameters:
  • name (string) – Name of the plugin to upgrade. The :latest tag is optional and is the default if omitted.
  • remote (string) – Remote reference to upgrade to. The :latest tag is optional and is the default if omitted.
  • privileges (list) – A list of privileges the user consents to grant to the plugin. Can be retrieved using plugin_privileges().
Returns:

An iterable object streaming the decoded API logs

Secrets

class SecretApiMixin
create_secret(name, data, labels=None, driver=None)

Create a secret

Parameters:
  • name (string) – Name of the secret
  • data (bytes) – Secret data to be stored
  • labels (dict) – A mapping of labels to assign to the secret
  • driver (DriverConfig) – A custom driver configuration. If unspecified, the default internal driver will be used

Returns (dict): ID of the newly created secret

inspect_secret(id)

Retrieve secret metadata

Parameters:id (string) – Full ID of the secret to remove

Returns (dict): A dictionary of metadata

Raises:docker.errors.NotFound – if no secret with that ID exists
remove_secret(id)

Remove a secret

Parameters:id (string) – Full ID of the secret to remove

Returns (boolean): True if successful

Raises:docker.errors.NotFound – if no secret with that ID exists
secrets(filters=None)

List secrets

Parameters:
  • filters (dict) – A map of filters to process on the secrets
  • Available filters (list.) – names

Returns (list): A list of secrets

The Docker daemon

class DaemonApiMixin
df()

Get data usage information.

Returns:A dictionary representing different resource categories and their respective data usage.
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
events(since=None, until=None, filters=None, decode=None)

Get real-time events from the server. Similar to the docker events command.

Parameters:
  • since (UTC datetime or int) – Get events from this point
  • until (UTC datetime or int) – Get events until this point
  • filters (dict) – Filter the events by event time, container or image
  • decode (bool) – If set to true, stream will be decoded into dicts on the fly. False by default.
Returns:

A blocking generator you can iterate over to retrieve

events as they happen.

Return type:

(generator)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> for event in client.events()
...   print event
{u'from': u'image/with:tag',
 u'id': u'container-id',
 u'status': u'start',
 u'time': 1423339459}
...
info()

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

Returns:The info as a dict
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.
login(username, password=None, email=None, registry=None, reauth=False, insecure_registry=False, dockercfg_path=None)

Authenticate with a registry. Similar to the docker login command.

Parameters:
  • username (str) – The registry username
  • password (str) – The plaintext password
  • email (str) – The email for the registry account
  • registry (str) – URL to the registry. E.g. https://index.docker.io/v1/
  • reauth (bool) – Whether or not to refresh existing authentication on the Docker server.
  • dockercfg_path (str) – Use a custom path for the Docker config file (default $HOME/.docker/config.json if present, otherwise``$HOME/.dockercfg``)
Returns:

The response from the login request

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

ping()

Checks the server is responsive. An exception will be raised if it isn’t responding.

Returns:(bool) The response from the server.
Raises:docker.errors.APIError – If the server returns an error.
version(api_version=True)

Returns version information from the server. Similar to the docker version command.

Returns:The server version information
Return type:(dict)
Raises:docker.errors.APIError – If the server returns an error.

Configuration types

class ConfigReference(config_id, config_name, filename=None, uid=None, gid=None, mode=292)

Config reference to be used as part of a ContainerSpec. Describes how a config is made accessible inside the service’s containers.

Parameters:
  • config_id (string) – Config’s ID
  • config_name (string) – Config’s name as defined at its creation.
  • filename (string) – Name of the file containing the config. Defaults to the config’s name if not specified.
  • uid (string) – UID of the config file’s owner. Default: 0
  • gid (string) – GID of the config file’s group. Default: 0
  • mode (int) – File access mode inside the container. Default: 0o444
class ContainerSpec(image, command=None, args=None, hostname=None, env=None, workdir=None, user=None, labels=None, mounts=None, stop_grace_period=None, secrets=None, tty=None, groups=None, open_stdin=None, read_only=None, stop_signal=None, healthcheck=None, hosts=None, dns_config=None, configs=None, privileges=None)

Describes the behavior of containers that are part of a task, and is used when declaring a TaskTemplate.

Parameters:
  • image (string) – The image name to use for the container.
  • command (string or list) – The command to be run in the image.
  • args (list) – Arguments to the command.
  • hostname (string) – The hostname to set on the container.
  • env (dict) – Environment variables.
  • dir (string) – The working directory for commands to run in.
  • user (string) – The user inside the container.
  • labels (dict) – A map of labels to associate with the service.
  • mounts (list) – A list of specifications for mounts to be added to containers created as part of the service. See the Mount class for details.
  • stop_grace_period (int) – Amount of time to wait for the container to terminate before forcefully killing it.
  • secrets (list) – List of SecretReference to be made available inside the containers.
  • tty (boolean) – Whether a pseudo-TTY should be allocated.
  • groups (list) – A list of additional groups that the container process will run as.
  • open_stdin (boolean) – Open stdin
  • read_only (boolean) – Mount the container’s root filesystem as read only.
  • stop_signal (string) – Set signal to stop the service’s containers
  • healthcheck (Healthcheck) – Healthcheck configuration for this service.
  • hosts (dict) – A set of host to IP mappings to add to the container’s hosts file.
  • dns_config (DNSConfig) – Specification for DNS related configurations in resolver configuration file.
  • configs (list) – List of ConfigReference that will be exposed to the service.
  • privileges (Privileges) – Security options for the service’s containers.
class DNSConfig(nameservers=None, search=None, options=None)

Specification for DNS related configurations in resolver configuration file (resolv.conf). Part of a ContainerSpec definition.

Parameters:
  • nameservers (list) – The IP addresses of the name servers.
  • search (list) – A search list for host-name lookup.
  • options (list) – A list of internal resolver variables to be modified (e.g., debug, ndots:3, etc.).
class DriverConfig(name, options=None)

Indicates which driver to use, as well as its configuration. Can be used as log_driver in a ContainerSpec, for the driver_config in a volume Mount, or as the driver object in create_secret().

Parameters:
  • name (string) – Name of the driver to use.
  • options (dict) – Driver-specific options. Default: None.
class EndpointSpec(mode=None, ports=None)

Describes properties to access and load-balance a service.

Parameters:
  • mode (string) – The mode of resolution to use for internal load balancing between tasks ('vip' or 'dnsrr'). Defaults to 'vip' if not provided.
  • ports (dict) – Exposed ports that this service is accessible on from the outside, in the form of { target_port: published_port } or { target_port: (published_port, protocol) }. Ports can only be provided if the vip resolution mode is used.
class Healthcheck(**kwargs)

Defines a healthcheck configuration for a container or service.

Parameters:
  • test (list or str) –

    Test to perform to determine container health. Possible values:

    • Empty list: Inherit healthcheck from parent image
    • ["NONE"]: Disable healthcheck
    • ["CMD", args...]: exec arguments directly.
    • ["CMD-SHELL", command]: RUn command in the system’s default shell.

    If a string is provided, it will be used as a CMD-SHELL command.

  • interval (int) – The time to wait between checks in nanoseconds. It should be 0 or at least 1000000 (1 ms).
  • timeout (int) – The time to wait before considering the check to have hung. It should be 0 or at least 1000000 (1 ms).
  • retries (integer) – The number of consecutive failures needed to consider a container as unhealthy.
  • start_period (integer) – Start period for the container to initialize before starting health-retries countdown in nanoseconds. It should be 0 or at least 1000000 (1 ms).
class IPAMConfig(driver='default', pool_configs=None, options=None)

Create an IPAM (IP Address Management) config dictionary to be used with create_network().

Parameters:
  • driver (str) – The IPAM driver to use. Defaults to default.
  • pool_configs (list) – A list of pool configurations (IPAMPool). Defaults to empty list.
  • options (dict) – Driver options as a key-value dictionary. Defaults to None.

Example

>>> ipam_config = docker.types.IPAMConfig(driver='default')
>>> network = client.create_network('network1', ipam=ipam_config)
class IPAMPool(subnet=None, iprange=None, gateway=None, aux_addresses=None)

Create an IPAM pool config dictionary to be added to the pool_configs parameter of IPAMConfig.

Parameters:
  • subnet (str) – Custom subnet for this IPAM pool using the CIDR notation. Defaults to None.
  • iprange (str) – Custom IP range for endpoints in this IPAM pool using the CIDR notation. Defaults to None.
  • gateway (str) – Custom IP address for the pool’s gateway.
  • aux_addresses (dict) – A dictionary of key -> ip_address relationships specifying auxiliary addresses that need to be allocated by the IPAM driver.

Example

>>> ipam_pool = docker.types.IPAMPool(
    subnet='124.42.0.0/16',
    iprange='124.42.0.0/24',
    gateway='124.42.0.254',
    aux_addresses={
        'reserved1': '124.42.1.1'
    }
)
>>> ipam_config = docker.types.IPAMConfig(
        pool_configs=[ipam_pool])
class Mount(target, source, type='volume', read_only=False, consistency=None, propagation=None, no_copy=False, labels=None, driver_config=None, tmpfs_size=None, tmpfs_mode=None)

Describes a mounted folder’s configuration inside a container. A list of Mount would be used as part of a ContainerSpec.

Parameters:
  • target (string) – Container path.
  • source (string) – Mount source (e.g. a volume name or a host path).
  • type (string) – The mount type (bind / volume / tmpfs / npipe). Default: volume.
  • read_only (bool) – Whether the mount should be read-only.
  • consistency (string) – The consistency requirement for the mount. One of
  • consistent, cached, delegated. (default`,) –
  • propagation (string) – A propagation mode with the value [r]private, [r]shared, or [r]slave. Only valid for the bind type.
  • no_copy (bool) – False if the volume should be populated with the data from the target. Default: False. Only valid for the volume type.
  • labels (dict) – User-defined name and labels for the volume. Only valid for the volume type.
  • driver_config (DriverConfig) – Volume driver configuration. Only valid for the volume type.
  • tmpfs_size (int or string) – The size for the tmpfs mount in bytes.
  • tmpfs_mode (int) – The permission mode for the tmpfs mount.
class Placement(constraints=None, preferences=None, platforms=None)

Placement constraints to be used as part of a TaskTemplate

Parameters:
  • constraints (list) – A list of constraints
  • preferences (list) – Preferences provide a way to make the scheduler aware of factors such as topology. They are provided in order from highest to lowest precedence.
  • platforms (list) – A list of platforms expressed as (arch, os) tuples
class Privileges(credentialspec_file=None, credentialspec_registry=None, selinux_disable=None, selinux_user=None, selinux_role=None, selinux_type=None, selinux_level=None)

Security options for a service’s containers. Part of a ContainerSpec definition.

Parameters:
  • credentialspec_file (str) – Load credential spec from this file. The file is read by the daemon, and must be present in the CredentialSpecs subdirectory in the docker data directory, which defaults to C:\ProgramData\Docker\ on Windows. Can not be combined with credentialspec_registry.
  • credentialspec_registry (str) – Load credential spec from this value in the Windows registry. The specified registry value must be located in: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion \Virtualization\Containers\CredentialSpecs. Can not be combined with credentialspec_file.
  • selinux_disable (boolean) – Disable SELinux
  • selinux_user (string) – SELinux user label
  • selinux_role (string) – SELinux role label
  • selinux_type (string) – SELinux type label
  • selinux_level (string) – SELinux level label
class Resources(cpu_limit=None, mem_limit=None, cpu_reservation=None, mem_reservation=None)

Configures resource allocation for containers when made part of a ContainerSpec.

Parameters:
  • cpu_limit (int) – CPU limit in units of 10^9 CPU shares.
  • mem_limit (int) – Memory limit in Bytes.
  • cpu_reservation (int) – CPU reservation in units of 10^9 CPU shares.
  • mem_reservation (int) – Memory reservation in Bytes.
class RestartPolicy(condition='none', delay=0, max_attempts=0, window=0)

Used when creating a ContainerSpec, dictates whether a container should restart after stopping or failing.

Parameters:
  • condition (string) – Condition for restart (none, on-failure, or any). Default: none.
  • delay (int) – Delay between restart attempts. Default: 0
  • max_attempts (int) – Maximum attempts to restart a given container before giving up. Default value is 0, which is ignored.
  • window (int) – Time window used to evaluate the restart policy. Default value is 0, which is unbounded.
class SecretReference(secret_id, secret_name, filename=None, uid=None, gid=None, mode=292)

Secret reference to be used as part of a ContainerSpec. Describes how a secret is made accessible inside the service’s containers.

Parameters:
  • secret_id (string) – Secret’s ID
  • secret_name (string) – Secret’s name as defined at its creation.
  • filename (string) – Name of the file containing the secret. Defaults to the secret’s name if not specified.
  • uid (string) – UID of the secret file’s owner. Default: 0
  • gid (string) – GID of the secret file’s group. Default: 0
  • mode (int) – File access mode inside the container. Default: 0o444
class ServiceMode(mode, replicas=None)

Indicate whether a service should be deployed as a replicated or global service, and associated parameters

Parameters:
  • mode (string) – Can be either replicated or global
  • replicas (int) – Number of replicas. For replicated services only.
class SwarmExternalCA(url, protocol=None, options=None, ca_cert=None)

Configuration for forwarding signing requests to an external certificate authority.

Parameters:
  • url (string) – URL where certificate signing requests should be sent.
  • protocol (string) – Protocol for communication with the external CA.
  • options (dict) – An object with key/value pairs that are interpreted as protocol-specific options for the external CA driver.
  • ca_cert (string) – The root CA certificate (in PEM format) this external CA uses to issue TLS certificates (assumed to be to the current swarm root CA certificate if not provided).
class SwarmSpec(*args, **kwargs)

Describe a Swarm’s configuration and options. Use create_swarm_spec() to instantiate.

class TaskTemplate(container_spec, resources=None, restart_policy=None, placement=None, log_driver=None, force_update=None)

Describe the task specification to be used when creating or updating a service.

Parameters:
  • container_spec (ContainerSpec) – Container settings for containers started as part of this task.
  • log_driver (DriverConfig) – Log configuration for containers created as part of the service.
  • resources (Resources) – Resource requirements which apply to each individual container created as part of the service.
  • restart_policy (RestartPolicy) – Specification for the restart policy which applies to containers created as part of this service.
  • placement (Placement) – Placement instructions for the scheduler. If a list is passed instead, it is assumed to be a list of constraints as part of a Placement object.
  • force_update (int) – A counter that triggers an update even if no relevant parameters have been changed.
class UpdateConfig(parallelism=0, delay=None, failure_action='continue', monitor=None, max_failure_ratio=None)

Used to specify the way container updates should be performed by a service.

Parameters:
  • parallelism (int) – Maximum number of tasks to be updated in one iteration (0 means unlimited parallelism). Default: 0.
  • delay (int) – Amount of time between updates.
  • failure_action (string) – Action to take if an updated task fails to run, or stops running during the update. Acceptable values are continue and pause. Default: continue
  • monitor (int) – Amount of time to monitor each updated task for failures, in nanoseconds.
  • max_failure_ratio (float) – The fraction of tasks that may fail during an update before the failure action is invoked, specified as a floating point number between 0 and 1. Default: 0