Containers¶
Run and manage containers on the server.
Methods available on client.containers
:
Container objects¶
- class Container¶
Local representation of a container object. Detailed configuration may be accessed through the
attrs
attribute. Note that local attributes are cached; users may callreload()
to query the Docker daemon for the current properties, causingattrs
to be refreshed.- 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 12 characters.
- status¶
The status of the container. For example,
running
, orexited
.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
pause (bool) – Whether to pause the container before committing
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:
- (list) A list of dictionaries containing the attributes Path
and Kind.
- 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, workdir=None, demux=False)¶
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
socket (bool) – Return the connection socket to allow custom read/write operations. Default: False
environment (dict or list) – A dictionary or a list of strings in the following format
["PASSWORD=xxx"]
or{"PASSWORD": "xxx"}
.workdir (str) – Path to working directory for this exec session
demux (bool) – Return stdout and stderr separately
- Returns:
- A tuple of (exit_code, output)
- exit_code: (int):
Exit code for the executed command or
None
if eitherstream
orsocket
isTrue
.- output: (generator, bytes, or tuple):
If
stream=True
, a generator yielding response chunks. Ifsocket=True
, a socket object for the connection. Ifdemux=True
, a tuple of two bytes: stdout and stderr. A bytestring containing response data otherwise.
- Return type:
(ExecResult)
- Raises:
docker.errors.APIError – If the server returns an error.
- export(chunk_size=2097152)¶
Export the contents of the container’s filesystem as a tar archive.
- Parameters:
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:
The filesystem tar archive
- Return type:
(str)
- Raises:
docker.errors.APIError – If the server returns an error.
- get_archive(path, chunk_size=2097152, encode_stream=False)¶
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
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 MBencode_stream (bool) – Determines if data should be encoded (gzip-compressed) during transmission. Default: False
- Returns:
First element is a raw tar data stream. Second element is a dict containing
stat
information on the specifiedpath
.- Return type:
(tuple)
- Raises:
docker.errors.APIError – If the server returns an error.
Example
>>> f = open('./sh_bin.tar', 'wb') >>> bits, stat = container.get_archive('/bin/sh') >>> print(stat) {'name': 'sh', 'size': 1075464, 'mode': 493, 'mtime': '2018-10-01T15:37:48-07:00', 'linkTarget': ''} >>> for chunk in bits: ... f.write(chunk) >>> f.close()
- 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 thelogs
function return a blocking generator you can iterate over to retrieve log output as it happens.- Parameters:
stdout (bool) – Get
STDOUT
. DefaultTrue
stderr (bool) – Get
STDERR
. DefaultTrue
stream (bool) – Stream the response. Default
False
timestamps (bool) – Show timestamps. Default
False
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
. Defaultall
since (datetime, int, or float) – Show logs since a given datetime, integer epoch (in seconds) or float (in nanoseconds)
follow (bool) – Follow log output. Default
False
until (datetime, int, or float) – Show logs that occurred before the given datetime, integer epoch (in seconds), or float (in nanoseconds)
- Returns:
Logs from the container.
- Return type:
(generator of bytes or bytes)
- 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 or stream) – tar data to be extracted
- Returns:
True if the call succeeds.
- Return type:
(bool)
- Raises:
APIError –
- 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. Only applicable if
stream
is True. 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
condition (str) – Wait until a container state reaches the given condition, either
not-running
(default),next-exit
, orremoved
- Returns:
- The API’s response as a Python dictionary, including
the container’s exit code under the
StatusCode
attribute.
- Return type:
(dict)
- Raises:
requests.exceptions.ReadTimeout – If the timeout is exceeded.
docker.errors.APIError – If the server returns an error.