api.container

Module Contents

Classes

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

Args:

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.

Args:

container (str): The container to attach to. params (dict): Dictionary of request parameters (e.g. stdout,

stderr, stream). For detachKeys, ~/.docker/config.json is used by default.

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.

Args:

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=None, size=False, filters=None)

List containers. Similar to the docker ps command.

Args:

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.
create_container(image, command=None, hostname=None, user=None, detach=False, stdin_open=False, tty=False, ports=None, environment=None, volumes=None, network_disabled=False, name=None, entrypoint=None, working_dir=None, domainname=None, host_config=None, mac_address=None, labels=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
)
Args:

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 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"}.
volumes (str or list): List of paths inside the container to use
as volumes.

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 host_config (dict): A dictionary created with

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"])
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_host_config()

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

Args:
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_cgroup_rules (list): A list of cgroup rules to
apply to the container.
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().

Args:
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
)
create_endpoint_config(*args, **kwargs)

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

Args:
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'
)
diff(container)

Inspect changes on a container’s filesystem.

Args:
container (str): The container to diff
Returns:
(str)
Raises:
docker.errors.APIError
If the server returns an error.
export(container, chunk_size=DEFAULT_DATA_CHUNK_SIZE)

Export the contents of a filesystem as a tar archive.

Args:

container (str): The container to export chunk_size (int): The number of bytes returned by each iteration

of the generator. If None, data will be streamed as it is received. Default: 2 MB
Returns:
(generator): The archived filesystem data stream
Raises:
docker.errors.APIError
If the server returns an error.
get_archive(container, path, chunk_size=DEFAULT_DATA_CHUNK_SIZE)

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

Args:

container (str): The container where the file is located path (str): Path to the file or folder to retrieve chunk_size (int): The number of bytes returned by each iteration

of the generator. If None, data will be streamed as it is received. Default: 2 MB
Returns:
(tuple): First element is a raw tar data stream. Second element is a dict containing stat information on the specified path.
Raises:
docker.errors.APIError
If the server returns an error.
inspect_container(container)

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

Args:
container (str): The container to inspect
Returns:
(dict): Similar to the output of docker inspect, but as a single 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.

Args:
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, until=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.

Args:

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 until (datetime or int): Show logs that occurred before the given

datetime or integer epoch (in seconds)
Returns:
(generator or str)
Raises:
docker.errors.APIError
If the server returns an error.
pause(container)

Pauses all processes within a container.

Args:
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.

Args:
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
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'}]
put_archive(container, path, data)

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

Args:

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:
(bool): True if the call succeeds.
Raises:
docker.errors.APIError
If the server returns an error.
prune_containers(filters=None)

Delete stopped containers

Args:
filters (dict): Filters to process on the prune list.
Returns:
(dict): A dict containing a list of deleted container IDs and
the amount of disk space reclaimed in bytes.
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.

Args:

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.

Args:
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.

Args:
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.

Args:
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().

Args:
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.

Args:

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=None)

Stops a container. Similar to the docker stop command.

Args:

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

stop before sending a SIGKILL. If None, then the StopTimeout value of the container will be used. Default: None
Raises:
docker.errors.APIError
If the server returns an error.
top(container, ps_args=None)

Display the running processes of a container.

Args:
container (str): The container to inspect ps_args (str): An optional arguments passed to ps (e.g. aux)
Returns:
(str): The output of the top
Raises:
docker.errors.APIError
If the server returns an error.
unpause(container)

Unpause all processes within a container.

Args:
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.

Args:

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:
(dict): Dictionary containing a Warnings key.
Raises:
docker.errors.APIError
If the server returns an error.
wait(container, timeout=None, condition=None)

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

Args:
container (str or dict): The container to wait on. If a dict, the
Id key is used.

timeout (int): Request timeout condition (str): Wait until a container state reaches the given

condition, either not-running (default), next-exit, or removed
Returns:
(dict): The API’s response as a Python dictionary, including
the container’s exit code under the StatusCode attribute.
Raises:
requests.exceptions.ReadTimeout
If the timeout is exceeded.
docker.errors.APIError
If the server returns an error.