Containers

Run and manage containers on the server.

Methods available on client.containers:

class ContainerCollection(client=None)
run(image, command=None, **kwargs)

Run a container. By default, it will wait for the container to finish and return its logs, similar to docker run.

If the detach argument is True, it will start the container and immediately return a Container object, similar to docker run -d.

Example

Run a container and get its output:

>>> import docker
>>> client = docker.from_env()
>>> client.containers.run('alpine', 'echo hello world')
b'hello world\n'

Run a container and detach:

>>> container = client.containers.run('bfirsh/reticulate-splines',
                                      detach=True)
>>> container.logs()
'Reticulating spline 1...\nReticulating spline 2...\n'
Parameters:
  • image (str) – The image to run.
  • command (str or list) – The command to run in the container.
  • auto_remove (bool) – enable auto-removal of the container on daemon side when the container’s process exits.
  • 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_count (int) – Number of usable CPUs (Windows only).
  • cpu_percent (int) – Usable percentage of the available CPUs (Windows only).
  • 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.
  • detach (bool) – Run container in the background and return a Container object.
  • 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.
  • domainname (str or list) – Set custom DNS search domains.
  • entrypoint (str or list) – The entrypoint for the container.
  • environment (dict or list) – Environment variables to set inside the container, as a dictionary or a list of strings in the format ["SOMEVARIABLE=xxx"].
  • 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.
  • healthcheck (dict) – Specify a test to perform to check that the container is healthy.
  • hostname (str) – Optional hostname for the container.
  • 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.
  • 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"])
  • 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.
  • mac_address (str) – MAC address to assign to the container.
  • mem_limit (int 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.
  • 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.
  • name (str) – The name for this container.
  • nano_cpus (int) – CPU quota in units of 10-9 CPUs.
  • network (str) – Name of the network this container will be connected to at creation time. You can connect to additional networks using Network.connect(). Incompatible with network_mode.
  • network_disabled (bool) – Disable networking.
  • 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.

    Incompatible with network.

  • 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.
  • ports (dict) –

    Ports to bind inside the container.

    The keys of the dictionary are the ports to bind inside the container, either as an integer or a string in the form port/protocol, where the protocol is either tcp or udp.

    The values of the dictionary are the corresponding ports to open on the host, which can be either:

    • The port number, as an integer. For example, {'2222/tcp': 3333} will expose port 2222 inside the container as port 3333 on the host.
    • None, to assign a random host port. For example, {'2222/tcp': None}.
    • A tuple of (address, port) if you want to specify the host interface. For example, {'1111/tcp': ('127.0.0.1', 1111)}.
    • A list of integers, if you want to bind multiple host ports to a single container port. For example, {'1111/tcp': [1234, 4567]}.
  • 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.
  • remove (bool) – Remove the container when it has finished running. Default: False.
  • 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.

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

  • 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).
  • stdin_open (bool) – Keep STDIN open even if not attached.
  • stdout (bool) – Return logs from STDOUT when detach=False. Default: True.
  • stderr (bool) – Return logs from STDERR when detach=False. Default: False.
  • stop_signal (str) – The stop signal to use to stop the container (e.g. SIGINT).
  • 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'
    }
    
  • tty (bool) – Allocate a pseudo-TTY.
  • ulimits (list) – Ulimits to set inside the container, as a list of dicts.
  • user (str or int) – Username or UID to run commands as inside the container.
  • userns_mode (str) – Sets the user namespace mode for the container when user namespace remapping option is enabled. Supported values are: host
  • volume_driver (str) – The name of a volume driver/plugin.
  • volumes (dict or list) –

    A dictionary to configure volumes mounted inside the container. The key is either the host path or a volume name, and the value is a dictionary with the keys:

    • bind The path to mount the volume inside the container
    • mode Either rw to mount the volume read/write, or ro to mount it read-only.

    For example:

    {'/home/user1/': {'bind': '/mnt/vol2', 'mode': 'rw'},
     '/var/www': {'bind': '/mnt/vol1', 'mode': 'ro'}}
    
  • volumes_from (list) – List of container names or IDs to get volumes from.
  • working_dir (str) – Path to the working directory.
  • runtime (str) – Runtime to use with this container.
Returns:

The container logs, either STDOUT, STDERR, or both, depending on the value of the stdout and stderr arguments.

STDOUT and STDERR may be read only if either json-file or journald logging driver used. Thus, if you are using none of these drivers, a None object is returned instead. See the Engine API documentation for full details.

If detach is True, a Container object is returned instead.

Raises:
  • docker.errors.ContainerError – If the container exits with a non-zero exit code and detach is False.
  • docker.errors.ImageNotFound – If the specified image does not exist.
  • docker.errors.APIError – If the server returns an error.
create(image, command=None, **kwargs)

Create a container without starting it. Similar to docker create.

Takes the same arguments as run(), except for stdout, stderr, and remove.

Returns:

A Container object.

Raises:
  • docker.errors.ImageNotFound – If the specified image does not exist.
  • docker.errors.APIError – If the server returns an error.
get(id_or_name)

Get a container by name or ID.

Parameters:

container_id (str) – Container name or ID.

Returns:

A Container object.

Raises:
  • docker.errors.NotFound – If the container does not exist.
  • docker.errors.APIError – If the server returns an error.
list(**kwargs)

List containers. Similar to the docker ps command.

Parameters:
  • all (bool) – Show all containers. Only running containers are shown by default
  • 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
  • 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:

(list of Container)

Raises:

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

prune(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.

Container objects

class Container
attrs
id

The ID of the object.

image

The image of the container.

labels

The labels of a container as dictionary.

name

The name of the container.

short_id

The ID of the object, truncated to 10 characters.

status

The status of the container. For example, running, or exited. The raw representation of this object from the server.

attach(**kwargs)

Attach to this container.

logs() 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:
  • 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(**kwargs)

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

Parameters:
  • 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(repository=None, tag=None, **kwargs)

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

Parameters:
  • 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.

diff()

Inspect changes on a container’s filesystem.

Returns:(str)
Raises:docker.errors.APIError – If the server returns an error.
exec_run(cmd, stdout=True, stderr=True, stdin=False, tty=False, privileged=False, user='', detach=False, stream=False, socket=False, environment=None)

Run a command inside this container. Similar to docker exec.

Parameters:
  • 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
  • detach (bool) – If true, detach from the exec command. Default: False
  • stream (bool) – Stream response data. Default: False
  • environment (dict or list) – A dictionary or a list of strings in the following format ["PASSWORD=xxx"] or {"PASSWORD": "xxx"}.
Returns:

If stream=True, a generator yielding

response chunks. A string containing response data otherwise.

Return type:

(generator or str)

Raises:

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

export()

Export the contents of the container’s filesystem as a tar archive.

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

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

Parameters: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.
kill(signal=None)

Kill or send a signal to the container.

Parameters:signal (str or int) – The signal to send. Defaults to SIGKILL
Raises:docker.errors.APIError – If the server returns an error.
logs(**kwargs)

Get logs from this 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:
  • 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:

Logs from the container.

Return type:

(generator or str)

Raises:

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

pause()

Pauses all processes within this container.

Raises:docker.errors.APIError – If the server returns an error.
put_archive(path, data)

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

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

APIError If an error occurs.

reload()

Load this object from the server again and update attrs with the new data.

remove(**kwargs)

Remove this container. Similar to the docker rm command.

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

Rename this container. Similar to the docker rename command.

Parameters:name (str) – New name for the container
Raises:docker.errors.APIError – If the server returns an error.
resize(height, width)

Resize the tty session.

Parameters:
  • height (int) – Height of tty session
  • width (int) – Width of tty session
Raises:

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

restart(**kwargs)

Restart this container. Similar to the docker restart command.

Parameters: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(**kwargs)

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

Raises:docker.errors.APIError – If the server returns an error.
stats(**kwargs)

Stream statistics for this container. Similar to the docker stats command.

Parameters:
  • 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(**kwargs)

Stops a container. Similar to the docker stop command.

Parameters: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(**kwargs)

Display the running processes of the container.

Parameters: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()

Unpause all processes within the container.

Raises:docker.errors.APIError – If the server returns an error.
update(**kwargs)

Update resource configuration of the containers.

Parameters:
  • 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(**kwargs)

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

Parameters:

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.