docker container

ContainerCLI

attach

attach(container, detach_keys=None, stdin=True, sig_proxy=True)

Attach local standard input, output, and error streams to a running container

Alias: docker.attach(...)

PARAMETER	DESCRIPTION
`container`	The running container to attach to TYPE: `ValidContainer`
`detach_keys`	Override the key sequence for detaching a container TYPE: `Optional[str]` DEFAULT: `None`
`stdin`	Attach STDIN TYPE: `bool` DEFAULT: `True`
`sig_proxy`	Proxy all received signals to the process (default true) TYPE: `bool` DEFAULT: `True`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

commit

commit(container, tag=None, author=None, message=None, pause=True)

Create a new image from a container's changes

PARAMETER	DESCRIPTION
`container`	The container to create the image from TYPE: `ValidContainer`
`tag`	tag to apply on the image produced TYPE: `Optional[str]` DEFAULT: `None`
`author`	Author (e.g., "John Hannibal Smith hannibal@a-team.com") TYPE: `Optional[str]` DEFAULT: `None`
`message`	Commit message TYPE: `Optional[str]` DEFAULT: `None`
`pause`	Pause container during commit TYPE: `bool` DEFAULT: `True`

copy

copy(source, destination)

Copy files/folders between a container and the local filesystem

Alias: docker.copy(...)

from python_on_whales import docker

docker.run("ubuntu", ["sleep", "infinity"], name="dodo", remove=True, detach=True)

docker.copy("/tmp/my_local_file.txt", ("dodo", "/path/in/container.txt"))
docker.copy(("dodo", "/path/in/container.txt"), "/tmp/my_local_file2.txt")

Doesn't yet support sending or receiving iterators of Python bytes.

PARAMETER	DESCRIPTION
`source`	Local path or tuple. When using a tuple, the first element of the tuple is the container, the second element is the path in the container. ex: `source=("my-container", "/usr/bin/something")`. TYPE: `Union[ValidPath, ContainerPath]`
`destination`	Local path or tuple. When using a tuple, the first element of the tuple is the container, the second element is the path in the container. ex: `source=("my-container", "/usr/bin/something")`. TYPE: `Union[ValidPath, ContainerPath]`

create

create(image, command=(), *, add_hosts=(), blkio_weight=None, blkio_weight_device=(), cap_add=(), cap_drop=(), cgroup_parent=None, cgroupns=None, cidfile=None, cpu_period=None, cpu_quota=None, cpu_rt_period=None, cpu_rt_runtime=None, cpu_shares=None, cpus=None, cpuset_cpus=None, cpuset_mems=None, detach=False, devices=(), device_cgroup_rules=(), device_read_bps=(), device_read_iops=(), device_write_bps=(), device_write_iops=(), content_trust=False, dns=(), dns_options=(), dns_search=(), domainname=None, entrypoint=None, envs={}, env_files=[], env_host=False, expose=(), gpus=None, groups_add=(), healthcheck=True, health_cmd=None, health_interval=None, health_retries=None, health_start_period=None, health_timeout=None, hostname=None, init=False, interactive=False, ip=None, ip6=None, ipc=None, isolation=None, kernel_memory=None, labels={}, label_files=(), link=(), link_local_ip=(), log_driver=None, log_options=(), mac_address=None, memory=None, memory_reservation=None, memory_swap=None, memory_swappiness=None, mounts=(), name=None, networks=(), network_aliases=(), oom_kill=True, oom_score_adj=None, pid=None, pids_limit=None, platform=None, pod=None, privileged=False, publish=(), publish_all=False, pull='missing', read_only=False, restart=None, remove=False, runtime=None, security_options=(), shm_size=None, sig_proxy=True, stop_signal=None, stop_timeout=None, storage_options=(), sysctl={}, systemd=None, tmpfs=(), tty=False, tz=None, ulimit=(), user=None, userns=None, uts=None, volumes=(), volume_driver=None, volumes_from=(), workdir=None)

Creates a container, but does not start it.

Alias: docker.create(...)

Start it then with the .start() method.

It might be useful if you want to delay the start of a container, to do some preparations beforehand. For example, it's common to do this workflow: docker create -> docker cp -> docker start to put files in the container before starting.

There is no detach argument since it's a runtime option.

The arguments are the same as docker.run.

diff

diff(container)

List all the files modified, added or deleted since the container started.

Alias: docker.diff(...)

PARAMETER	DESCRIPTION
`container`	The container to inspect TYPE: `ValidContainer`

Returns

`Dict[str, str]` Something like
`{"/some_path": "A", "/some_file": "M", "/tmp": "D"}` for example.

execute

execute(container, command, detach=False, envs={}, env_files=(), interactive=False, privileged=False, tty=False, user=None, workdir=None, stream=False, detach_keys=None, preserve_fds=None)

Execute a command inside a container

Alias: docker.execute(...)

PARAMETER	DESCRIPTION
`container`	The container to execute the command in. TYPE: `ValidContainer`
`command`	The command to execute. TYPE: `Sequence[str]`
`detach`	if `True`, returns immediately with `None`. If `False`, returns the command stdout as string. TYPE: `bool` DEFAULT: `False`
`envs`	Set environment variables TYPE: `Mapping[str, str]` DEFAULT: `{}`
`env_files`	Read one or more files of environment variables TYPE: `Union[ValidPath, Iterable[ValidPath]]` DEFAULT: `()`
`interactive`	Leave stdin open during the duration of the process to allow communication with the parent process. Currently only works with `tty=True` for interactive use on the terminal. TYPE: `bool` DEFAULT: `False`
`preserve_fds`	The number of additional file descriptors to pass through to the container. Only supported by podman. TYPE: `Optional[int]` DEFAULT: `None`
`privileged`	Give extended privileges to the container. TYPE: `bool` DEFAULT: `False`
`tty`	Allocate a pseudo-TTY. Allow the process to access your terminal to write on it. TYPE: `bool` DEFAULT: `False`
`user`	Username or UID, format: `"<name\|uid>[:<group\|gid>]"` TYPE: `Optional[str]` DEFAULT: `None`
`workdir`	Working directory inside the container TYPE: `Optional[ValidPath]` DEFAULT: `None`
`stream`	Similar to `docker.run(..., stream=True)`. TYPE: `bool` DEFAULT: `False`
`detach_keys`	Override the key sequence for detaching a container. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Union[None, str, Iterable[Tuple[str, bytes]]]`	Optional[str]

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

exists

exists(x)

Returns True if the container exists. False otherwise.

It's just calling docker.container.inspect(...) and verifies that it doesn't throw a python_on_whales.exceptions.NoSuchContainer.

Returns

A `bool`

export

export(container, output)

Export a container's filesystem as a tar archive

Alias: docker.export(...)

PARAMETER	DESCRIPTION
`container`	The container to export. TYPE: `ValidContainer`
`output`	The path of the output tar archive. Returning a generator of bytes is not yet implemented. TYPE: `ValidPath`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

init

init(containers)

Initialize one or more containers.

Note that this is only supported by podman.

Alias: docker.init(...)

PARAMETER	DESCRIPTION
`containers`	One or more containers to kill TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`output`	The path of the output tar archive. Returning a generator of bytes is not yet implemented.

Raises

`python_on_whales.exceptions.NoSuchContainer` if any of the
containers do not exist.

inspect

inspect(x)

Returns a container object from a name or ID.

PARAMETER	DESCRIPTION
`x`	A container name or ID, or a list of container names and/or IDs TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`

RETURNS	DESCRIPTION
`Union[Container, List[Container]]`	A `python_on_whales.Container` object or a list of those
`Union[Container, List[Container]]`	if a list of IDs was passed as input.

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

kill

kill(containers, signal=None)

Kill one or more containers.

Alias: docker.kill(...)

PARAMETER	DESCRIPTION
`containers`	One or more containers to kill TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`signal`	The signal to send the container TYPE: `Optional[Union[int, str]]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchContainer` if any of the
containers do not exist.

list

list(all=False, filters={})

List the containers on the host.

Alias: docker.ps(...)

PARAMETER	DESCRIPTION
`all`	If `True`, also returns containers that are not running. TYPE: `bool` DEFAULT: `False`

Returns

A `List[python_on_whales.Container]`

logs

logs(container, *, details=False, since=None, tail=None, timestamps=False, until=None, follow=False, stream=False)

Returns the logs of a container as a string or an iterator.

Alias: docker.logs(...)

PARAMETER	DESCRIPTION
`container`	The container to get the logs of TYPE: `ValidContainer`
`details`	Show extra details provided to logs TYPE: `bool` DEFAULT: `False`
`since`	Use a datetime or timedelta to specify the lower date limit for the logs. TYPE: `Union[None, datetime, timedelta]` DEFAULT: `None`
`tail`	Number of lines to show from the end of the logs (default all) TYPE: `Optional[int]` DEFAULT: `None`
`timestamps`	Put timestamps next to lines. TYPE: `bool` DEFAULT: `False`
`until`	Use a datetime or a timedelta to specify the upper date limit for the logs. TYPE: `Union[None, datetime, timedelta]` DEFAULT: `None`
`follow`	If `False` (the default), the logs returned are the logs up to the time of the function call. If `True`, the logs of the container up to the time the container stopped are displayed. Which means that if the container isn't stopped yet, the function will continue until the container is stopped. Which is why it is advised to use the `stream` option if you use the `follow` option. Without `stream`, only a `str` will be returned, possibly much later in the future. With `stream`, you'll be able to read the logs in real time. TYPE: `bool` DEFAULT: `False`
`stream`	Similar to the `stream` argument of `docker.run`. This function will then return an iterator that will yield a tuple `(source, content)` with `source` being `"stderr"` or `"stdout"`. `content` is the content of the line as bytes. Take a look at the user guide to have an example of the output. TYPE: `bool` DEFAULT: `False`

Returns

`str` if `stream=False` (the default), `Iterable[Tuple[str, bytes]]`
if `stream=True`.

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exist.

If you are a bit confused about follow and stream, here are some use cases.

If you want to have the logs up to this point as a str, don't use those args.
If you want to stream the output in real time, use follow=True, stream=True
If you want the logs up to this point, but you don't want to fit all the logs in memory because they are too big, use stream=True.

pause

pause(containers)

Pauses one or more containers

Alias: docker.pause(...)

PARAMETER	DESCRIPTION
`containers`	One or more containers to pause TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

prune

prune(filters={}, stream_logs=False)

Remove containers that are not running.

PARAMETER	DESCRIPTION
`filters`	Filters as strings or list of strings TYPE: `Dict[str, str]` DEFAULT: `{}`
`stream_logs`	If `True` this function will return an iterator of strings. You can then read the logs as they arrive. If `False` (the default value), then the function returns `None`, but when it returns, then the prune operation has already been done. TYPE: `bool` DEFAULT: `False`

remove

remove(containers, *, force=False, volumes=False)

Removes a container

Alias: docker.remove(...)

PARAMETER	DESCRIPTION
`containers`	One or more containers. TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`force`	Force the removal of a running container (uses SIGKILL) TYPE: `bool` DEFAULT: `False`
`volumes`	Remove anonymous volumes associated with the container TYPE: `bool` DEFAULT: `False`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

rename

rename(container, new_name)

Changes the name of a container.

Alias: docker.rename(...)

PARAMETER	DESCRIPTION
`container`	The container to rename TYPE: `ValidContainer`
`new_name`	The new name of the container. TYPE: `str`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exist.

restart

restart(containers, time=None)

Restarts one or more container.

Alias: docker.restart(...)

PARAMETER	DESCRIPTION
`containers`	One or more containers to restart TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`time`	Amount of to wait for stop before killing the container (default 10s). If `int`, the unit is seconds. TYPE: `Optional[Union[int, timedelta]]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

run

run(image, command=(), *, add_hosts=(), blkio_weight=None, blkio_weight_device=(), cap_add=(), cap_drop=(), cgroup_parent=None, cgroupns=None, cidfile=None, cpu_period=None, cpu_quota=None, cpu_rt_period=None, cpu_rt_runtime=None, cpu_shares=None, cpus=None, cpuset_cpus=None, cpuset_mems=None, detach=False, devices=(), device_cgroup_rules=(), device_read_bps=(), device_read_iops=(), device_write_bps=(), device_write_iops=(), content_trust=False, dns=(), dns_options=(), dns_search=(), domainname=None, entrypoint=None, envs={}, env_files=(), env_host=False, expose=(), gpus=None, groups_add=(), healthcheck=True, health_cmd=None, health_interval=None, health_retries=None, health_start_period=None, health_timeout=None, hostname=None, init=False, interactive=False, ip=None, ip6=None, ipc=None, isolation=None, kernel_memory=None, labels={}, label_files=(), link=(), link_local_ip=(), log_driver=None, log_options=(), mac_address=None, memory=None, memory_reservation=None, memory_swap=None, memory_swappiness=None, mounts=(), name=None, networks=(), network_aliases=(), oom_kill=True, oom_score_adj=None, pid=None, pids_limit=None, platform=None, pod=None, preserve_fds=None, privileged=False, publish=(), publish_all=False, pull='missing', read_only=False, restart=None, remove=False, runtime=None, security_options=(), shm_size=None, sig_proxy=True, stop_signal=None, stop_timeout=None, storage_options=(), stream=False, sysctl={}, systemd=None, tmpfs=(), tty=False, tz=None, ulimit=(), user=None, userns=None, uts=None, volumes=(), volume_driver=None, volumes_from=(), workdir=None)

Runs a container

You can use docker.run or docker.container.run to call this function.

For a deeper dive into the arguments and what they do, visit https://docs.docker.com/engine/reference/run/

If you want to know exactly how to call docker.run() depending on your use case (detach, stream...), take a look at the docker.run() guide.

>>> from python_on_whales import docker
>>> returned_string = docker.run("hello-world")
>>> print(returned_string)

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

>>> from python_on_whales import docker
>>> result_string = docker.run("ubuntu", ["ls", "/host"], volumes=[("/", "/host", "ro")])
>>> print(result_string)
bin
boot
dev
etc
home
init
lib
lib64
lost+found
media
mnt
opt
proc
projects
root
run
sbin
snap
srv
sys
tmp
usr
var

PARAMETER	DESCRIPTION
`image`	The image to use for the container. TYPE: `ValidImage`
`command`	Sequence of arguments to provide to the container. TYPE: `Sequence[str]` DEFAULT: `()`
`add_hosts`	hosts to add in the format of a tuple. For example, `add_hosts=[("my_host_1", "192.168.30.31"), ("host2", "192.168.80.81")]` TYPE: `Iterable[Tuple[str, str]]` DEFAULT: `()`
`blkio_weight`	Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) TYPE: `Optional[int]` DEFAULT: `None`
`cgroupns`	Cgroup namespace mode to use, one of 'host' or 'private'. TYPE: `Optional[str]` DEFAULT: `None`
`cpu_period`	Limit CPU CFS (Completely Fair Scheduler) period TYPE: `Optional[int]` DEFAULT: `None`
`cpu_quota`	Limit CPU CFS (Completely Fair Scheduler) quota TYPE: `Optional[int]` DEFAULT: `None`
`cpu_rt_period`	Limit CPU real-time period in microseconds TYPE: `Optional[int]` DEFAULT: `None`
`cpu_rt_runtime`	Limit CPU real-time runtime in microseconds TYPE: `Optional[int]` DEFAULT: `None`
`cpu_shares`	CPU shares (relative weight) TYPE: `Optional[int]` DEFAULT: `None`
`cpus`	The maximal amount of cpu the container can use. `1` means one cpu core. TYPE: `Optional[float]` DEFAULT: `None`
`cpuset_cpus`	CPUs in which to allow execution. Must be given as a list. TYPE: `Optional[List[int]]` DEFAULT: `None`
`cpuset_mems`	MEMs in which to allow execution. Must be given as a list. TYPE: `Optional[List[int]]` DEFAULT: `None`
`detach`	If `False`, returns the ouput of the container as a string. If `True`, returns a `python_on_whales.Container` object. TYPE: `bool` DEFAULT: `False`
`dns_search`	Set custom DNS search domains TYPE: `Iterable[str]` DEFAULT: `()`
`domainname`	Container NIS domain name TYPE: `Optional[str]` DEFAULT: `None`
`entrypoint`	Overwrite the default ENTRYPOINT of the image TYPE: `Optional[str]` DEFAULT: `None`
`envs`	Environment variables as a `dict`. For example: `{"OMP_NUM_THREADS": 3}` TYPE: `Mapping[str, str]` DEFAULT: `{}`
`env_files`	One or a list of env files. TYPE: `Union[ValidPath, Iterable[ValidPath]]` DEFAULT: `()`
`env_host`	Use host environment inside the container. Only supported with podman. TYPE: `bool` DEFAULT: `False`
`gpus`	For this to work, you need the Nvidia container runtime The value needed is a `str` or `int`. Some examples of valid argument are `"all"` or `"device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a"` or `"device=0,2"`. If you want 3 gpus, just write `gpus=3`. TYPE: `Union[int, str, None]` DEFAULT: `None`
`hostname`	Container host name TYPE: `Optional[str]` DEFAULT: `None`
`interactive`	Leave stdin open during the duration of the process to allow communication with the parent process. Currently only works with `tty=True` for interactive use on the terminal. TYPE: `bool` DEFAULT: `False`
`ip`	IPv4 address (e.g., 172.30.100.104) TYPE: `Optional[str]` DEFAULT: `None`
`ip6`	IPv6 address (e.g., 2001:db8::33) TYPE: `Optional[str]` DEFAULT: `None`
`ipc`	IPC mode to use TYPE: `Optional[str]` DEFAULT: `None`
`isolation`	Container isolation technology TYPE: `Optional[str]` DEFAULT: `None`
`kernel_memory`	Kernel memory limit. `int` represents the number of bytes, but you can use `"4k"` or `2g` for example. TYPE: `Union[int, str, None]` DEFAULT: `None`
`labels`	Set meta data on a container. The labels can be used later when filtering containers with `docker.ps(filters='...')`. The labels can also be found on each container with the attribute `my_container.config.labels`. TYPE: `Mapping[str, str]` DEFAULT: `{}`
`log_driver`	Logging driver for the container TYPE: `Optional[str]` DEFAULT: `None`
`mac_address`	Container MAC address (e.g., `"92:d0:c6:0a:29:33"`) TYPE: `Optional[str]` DEFAULT: `None`
`memory`	Memory limit, valid values are `1024` (ints are bytes) or `"43m"` or `"6g"`. TYPE: `Union[int, str, None]` DEFAULT: `None`
`memory_reservation`	Memory soft limit TYPE: `Union[int, str, None]` DEFAULT: `None`
`memory_swap`	Swap limit equal to memory plus swap: '-1' to enable unlimited swap. TYPE: `Union[int, str, None]` DEFAULT: `None`
`memory_swappiness`	Tune container memory swappiness (0 to 100) (default -1) TYPE: `Optional[int]` DEFAULT: `None`
`name`	The container name. If not provided, one is automatically genrated for you. TYPE: `Optional[str]` DEFAULT: `None`
`healthcheck`	Set to `False` to disable container periodic healthcheck. TYPE: `bool` DEFAULT: `True`
`oom_kill`	Set to `False` to disable the OOM killer for this container. TYPE: `bool` DEFAULT: `True`
`pid`	PID namespace to use TYPE: `Optional[str]` DEFAULT: `None`
`pids_limit`	Tune container pids limit (set `-1` for unlimited) TYPE: `Optional[int]` DEFAULT: `None`
`platform`	Set platform if server is multi-platform capable. TYPE: `Optional[str]` DEFAULT: `None`
`pod`	Create the container in an existing pod (only supported with podman). TYPE: `Optional[ValidPod]` DEFAULT: `None`
`preserve_fds`	The number of additional file descriptors to pass through to the container. Only supported by podman. TYPE: `Optional[int]` DEFAULT: `None`
`privileged`	Give extended privileges to this container. TYPE: `bool` DEFAULT: `False`
`publish`	Ports to publish, same as the `-p` argument in the Docker CLI. example are `[(8000, 7000) , ("127.0.0.1:3000", 2000)]` or `[("127.0.0.1:3000", 2000, "udp")]`. You can also use a single entry in the tuple to signify that you want a random free port on the host. For example: `publish=[(80,)]`. TYPE: `Iterable[ValidPortMapping]` DEFAULT: `()`
`publish_all`	Publish all exposed ports to random ports. TYPE: `bool` DEFAULT: `False`
`pull`	Pull image before running ("always"\|"missing"\|"never") (default "missing"). TYPE: `str` DEFAULT: `'missing'`
`read_only`	Mount the container's root filesystem as read only. TYPE: `bool` DEFAULT: `False`
`restart`	Restart policy to apply when a container exits (default "no") TYPE: `Optional[str]` DEFAULT: `None`
`remove`	Automatically remove the container when it exits. TYPE: `bool` DEFAULT: `False`
`runtime`	Runtime to use for this container. TYPE: `Optional[str]` DEFAULT: `None`
`security_options`	Security options TYPE: `Iterable[str]` DEFAULT: `()`
`shm_size`	Size of /dev/shm. `int` is for bytes. But you can use `"512m"` or `"4g"` for example. TYPE: `Union[int, str, None]` DEFAULT: `None`
`stop_timeout`	Signal to stop a container (default "SIGTERM") TYPE: `Optional[int]` DEFAULT: `None`
`storage_options`	Storage driver options for the container TYPE: `Iterable[str]` DEFAULT: `()`
`systemd`	Whether to run in systemd mode. Only known to apply to Podman, see https://docs.podman.io/en/latest/markdown/podman-run.1.html#systemd-true-false-always TYPE: `Optional[Union[bool, Literal['always']]]` DEFAULT: `None`
`tty`	Allocate a pseudo-TTY. Allow the process to access your terminal to write on it. TYPE: `bool` DEFAULT: `False`
`tz`	Set timezone in container, or `local` to match the host's timezone. See `/usr/share/zoneinfo/` for valid timezones. Note: This option is only known to apply to Podman containers. TYPE: `Optional[str]` DEFAULT: `None`
`user`	Username or UID (format: `<name\|uid>[:<group\|gid>]`) TYPE: `Optional[str]` DEFAULT: `None`
`userns`	User namespace to use TYPE: `Optional[str]` DEFAULT: `None`
`uts`	UTS namespace to use TYPE: `Optional[str]` DEFAULT: `None`
`volumes`	Bind mount a volume. Some examples: `[("/", "/host"), ("/etc/hosts", "/etc/hosts", "rw")]`. TYPE: `Iterable[VolumeDefinition]` DEFAULT: `()`
`volume_driver`	Optional volume driver for the container TYPE: `Optional[str]` DEFAULT: `None`
`workdir`	The directory in the container where the process will be executed. TYPE: `Optional[ValidPath]` DEFAULT: `None`

Returns

The container output as a string if detach is `False` (the default),
and a `python_on_whales.Container` if detach is `True`.

start

start(containers, attach=False, interactive=False, stream=False, detach_keys=None)

Starts one or more created/stopped containers.

Aliases: docker.start, docker.container.start, python_on_whales.Container.start.

PARAMETER	DESCRIPTION
`containers`	One or a list of containers. TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`attach`	Attach stdout/stderr and forward signals. TYPE: `bool` DEFAULT: `False`
`interactive`	Attach stdin (ensure it is open). TYPE: `bool` DEFAULT: `False`
`stream`	Stream output as a generator. TYPE: `bool` DEFAULT: `False`
`detach_keys`	Override the key sequence for detaching a container. TYPE: `Optional[str]` DEFAULT: `None`

stats

stats(containers=None, all=False)

Get containers resource usage statistics

Alias: docker.stats(...)

Usage:

from python_on_whales import docker

docker.run("redis", detach=True)
print(docker.stats())
# [<<class 'python_on_whales.components.container.ContainerStats'> object,
# attributes are block_read=0, block_write=0, cpu_percentage=0.08,
# container=e90ae41a5b17,
# container_id=e90ae41a5b17df998584141692f1e361c485e8d00c37ee21fdc360d3523dd1c1,
# memory_percentage=0.18, memory_used=11198791, memory_limit=6233071288,
# container_name=crazy_northcutt, net_upload=696, net_download=0>]

The data unit is the byte.

PARAMETER	DESCRIPTION
`all`	Get the stats of all containers, not just running ones. TYPE: `bool` DEFAULT: `False`
`containers`	One or a list of containers. TYPE: `Optional[Union[ValidContainer, Iterable[ValidContainer]]]` DEFAULT: `None`

Returns

A `List[python_on_whales.ContainerStats]`.

stop

stop(containers, time=None)

Stops one or more running containers

Alias: docker.stop(...)

Aliases: docker.stop, docker.container.stop, python_on_whales.Container.stop.

PARAMETER	DESCRIPTION
`containers`	One or a list of containers. TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`time`	Seconds to wait for stop before killing a container (default 10) TYPE: `Optional[Union[int, timedelta]]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchContainer` if any of the
containers do not exist.

top

top()

Get the running processes of a container

Alias: docker.top(...)

Not yet implemented

unpause

unpause(x)

Unpause all processes within one or more containers

Alias: docker.unpause(...)

PARAMETER	DESCRIPTION
`x`	One or more containers (name, id or `python_on_whales.Container` object). TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`

Raises

`python_on_whales.exceptions.NoSuchContainer` if any of the
containers do not exist.

update

update(x, /, *, blkio_weight=None, cpu_period=None, cpu_quota=None, cpu_rt_period=None, cpu_rt_runtime=None, cpu_shares=None, cpus=None, cpuset_cpus=None, cpuset_mems=None, kernel_memory=None, memory=None, memory_reservation=None, memory_swap=None, pids_limit=None, restart=None)

Update configuration of one or more containers

Alias: docker.update(...)

PARAMETER	DESCRIPTION
`x`	One or a list of containers to update. TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`
`blkio_weight`	Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) TYPE: `Optional[int]` DEFAULT: `None`
`cpu_period`	Limit CPU CFS (Completely Fair Scheduler) period TYPE: `Optional[int]` DEFAULT: `None`
`cpu_quota`	Limit CPU CFS (Completely Fair Scheduler) quota TYPE: `Optional[int]` DEFAULT: `None`
`cpu_rt_period`	Limit CPU real-time period in microseconds TYPE: `Optional[int]` DEFAULT: `None`
`cpu_rt_runtime`	Limit CPU real-time runtime in microseconds TYPE: `Optional[int]` DEFAULT: `None`
`cpu_shares`	CPU shares (relative weight) TYPE: `Optional[int]` DEFAULT: `None`
`cpus`	The maximal amount of cpu the container can use. `1` means one cpu core. TYPE: `Optional[float]` DEFAULT: `None`
`cpuset_cpus`	CPUs in which to allow execution. Must be given as a list. TYPE: `Optional[str]` DEFAULT: `None`
`cpuset_mems`	MEMs in which to allow execution. Must be given as a list. TYPE: `Optional[str]` DEFAULT: `None`
`memory`	Memory limit, valid values are `1024` (ints are bytes) or `"43m"` or `"6g"`. TYPE: `Union[int, str, None]` DEFAULT: `None`
`memory_reservation`	Memory soft limit TYPE: `Union[int, str, None]` DEFAULT: `None`
`memory_swap`	Swap limit equal to memory plus swap: '-1' to enable unlimited swap. TYPE: `Union[int, str, None]` DEFAULT: `None`
`pids_limit`	Tune container pids limit (set `-1` for unlimited) TYPE: `Optional[int]` DEFAULT: `None`
`restart`	Restart policy to apply when a container exits (default "no") TYPE: `Optional[str]` DEFAULT: `None`

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.

wait

wait(x)

Block until one or more containers stop, then returns their exit codes

Alias: docker.wait(...)

PARAMETER	DESCRIPTION
`x`	One or a list of containers to wait for. TYPE: `Union[ValidContainer, Iterable[ValidContainer]]`

Returns

An `int` if a single container was passed as argument or a list of ints
if multiple containers were passed as arguments.

Some Examples:

cont = docker.run("ubuntu", ["bash", "-c", "sleep 2 && exit 8"], detach=True)

exit_code = docker.wait(cont)

print(exit_code)
# 8
docker.container.remove(cont)

cont_1 = docker.run("ubuntu", ["bash", "-c", "sleep 4 && exit 8"], detach=True)
cont_2 = docker.run("ubuntu", ["bash", "-c", "sleep 2 && exit 10"], detach=True)

exit_codes = docker.wait([cont_1, cont_2])

print(exit_codes)
# [8, 10]
docker.container.remove([cont_1, cont_2])

Raises

`python_on_whales.exceptions.NoSuchContainer` if the container does not exists.