attach

docker.container.attach()

Not yet implemented

commit

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

Create a new image from a container's changes

Arguments

  • container Union[python_on_whales.Container, str]: The container to create the image from
  • tag Optional[str]: tag to apply on the image produced
  • author Optional[str]: Author (e.g., "John Hannibal Smith hannibal@a-team.com")
  • message Optional[str]: Commit message
  • pause bool: Pause container during commit

copy

docker.container.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.

Arguments

  • source Union[str, pathlib.Path, Tuple[Union[python_on_whales.Container, str], Union[str, pathlib.Path]]]: 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").
  • destination Union[str, pathlib.Path, Tuple[Union[python_on_whales.Container, str], Union[str, pathlib.Path]]]: 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").

create

docker.container.create(
    image,
    command=[],
    *,
    add_hosts=[],
    blkio_weight=None,
    blkio_weight_device=[],
    cap_add=[],
    cap_drop=[],
    cgroup_parent=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=[],
    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,
    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,
    privileged=False,
    publish=[],
    publish_all=False,
    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={},
    tmpfs=[],
    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

docker.container.diff(container)

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

Alias: docker.diff(...)

Arguments

  • container Union[python_on_whales.Container, str]: The container to inspect

Returns

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

execute

docker.container.execute(
    container,
    command,
    detach=False,
    envs={},
    env_files=[],
    interactive=False,
    privileged=False,
    tty=False,
    user=None,
    workdir=None,
    stream=False,
)

Execute a command inside a container

Alias: docker.execute(...)

Arguments

  • container Union[python_on_whales.Container, str]: The container to execute the command in.
  • command Union[str, List[str]]: The command to execute.
  • detach bool: if True, returns immediately with None. If False, returns the command stdout as string.
  • envs Dict[str, str]: Set environment variables
  • env_files Union[str, pathlib.Path, List[Union[str, pathlib.Path]]]: Read one or more files of environment variables
  • interactive bool: 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.
  • privileged bool: Give extended privileges to the container.
  • tty bool: Allocate a pseudo-TTY. Allow the process to access your terminal to write on it.
  • user Optional[str]: Username or UID, format: "<name|uid>[:<group|gid>]"
  • workdir Optional[Union[str, pathlib.Path]]: Working directory inside the container
  • stream bool: Similar to docker.run(..., stream=True).

Returns:

Optional[str]

Raises

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

exists

docker.container.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

docker.container.export(container, output)

Export a container's filesystem as a tar archive

Alias: docker.export(...)

Arguments

  • container Union[python_on_whales.Container, str]: The container to export.
  • output Union[str, pathlib.Path]: The path of the output tar archive. Returning a generator of bytes is not yet implemented.

Raises

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

inspect

docker.container.inspect(x)

Returns a container object from a name or ID.

Arguments

  • reference: A container name or ID, or a list of container names and/or IDs

Returns:

A python_on_whales.Container object or a list of those if a list of IDs was passed as input.

Raises

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

kill

docker.container.kill(containers, signal=None)

Kill a container.

Alias: docker.kill(...)

Arguments

  • containers Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or more containers to kill
  • signal Optional[str]: The signal to send the container

Raises

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

list

docker.container.list(all=False, filters={})

List the containers on the host.

Alias: docker.ps(...)

Arguments

  • all bool: If True, also returns containers that are not running.

Returns

A List[python_on_whales.Container]

logs

docker.container.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(...)

Arguments

  • container Union[python_on_whales.Container, str]: The container to get the logs of
  • details bool: Show extra details provided to logs
  • since Union[None, datetime.datetime, datetime.timedelta]: Use a datetime or timedelta to specify the lower date limit for the logs.
  • tail Optional[int]: Number of lines to show from the end of the logs (default all)
  • timestamps bool: Put timestamps next to lines.
  • until Union[None, datetime.datetime, datetime.timedelta]: Use a datetime or a timedelta to specify the upper date limit for the logs.
  • follow bool: 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.
  • stream bool: Similar to the stream argument of docker.run. This function will then returns and 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.

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 exists.

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

docker.container.pause(containers)

Pauses one or more containers

Alias: docker.pause(...)

Arguments

  • containers Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or more containers to pause

Raises

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

prune

docker.container.prune(filters={})

Remove containers that are not running.

Arguments

  • filters Dict[str, str]: Filters as strings or list of strings

remove

docker.container.remove(containers, force=False, volumes=False)

Removes a container

Alias: docker.remove(...)

Arguments

  • containers Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or more containers.
  • force bool: Force the removal of a running container (uses SIGKILL)
  • volumes bool: Remove anonymous volumes associated with the container

Raises

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

rename

docker.container.rename(container, new_name)

Changes the name of a container.

Alias: docker.rename(...)

Arguments

  • container Union[python_on_whales.Container, str]: The container to rename
  • new_name str: The new name of the container.

Raises

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

restart

docker.container.restart(containers, time=None)

Restarts one or more container.

Alias: docker.restart(...)

Arguments

  • containers Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or more containers to restart
  • time Optional[Union[int, datetime.timedelta]]: Amount of to wait for stop before killing the container (default 10s). If int, the unit is seconds.

Raises

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

run

docker.container.run(
    image,
    command=[],
    *,
    add_hosts=[],
    blkio_weight=None,
    blkio_weight_device=[],
    cap_add=[],
    cap_drop=[],
    cgroup_parent=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=[],
    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,
    privileged=False,
    publish=[],
    publish_all=False,
    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={},
    tmpfs=[],
    tty=False,
    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

Arguments

  • image Union[str, python_on_whales.Image]: The docker image to use for the container
  • command List[str]: List of arguments to provide to the container.
  • add_hosts List[Tuple[str, str]]: 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")]
  • blkio_weight Optional[int]: Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)
  • cpu_period Optional[int]: Limit CPU CFS (Completely Fair Scheduler) period
  • cpu_quota Optional[int]: Limit CPU CFS (Completely Fair Scheduler) quota
  • cpu_rt_period Optional[int]: Limit CPU real-time period in microseconds
  • cpu_rt_runtime Optional[int]: Limit CPU real-time runtime in microseconds
  • cpu_shares Optional[int]: CPU shares (relative weight)
  • cpus Optional[float]: The maximal amount of cpu the container can use. 1 means one cpu core.
  • cpuset_cpus Optional[List[int]]: CPUs in which to allow execution. Must be given as a list.
  • cpuset_mems Optional[List[int]]: MEMs in which to allow execution. Must be given as a list.
  • detach bool: If False, returns the ouput of the container as a string. If True, returns a python_on_whales.Container object.
  • dns_search List[str]: Set custom DNS search domains
  • domainname Optional[str]: Container NIS domain name
  • entrypoint Optional[str]: Overwrite the default ENTRYPOINT of the image
  • envs Dict[str, str]: Environment variables as a dict. For example: {"OMP_NUM_THREADS": 3}
  • env_files Union[str, pathlib.Path, List[Union[str, pathlib.Path]]]: One or a list of env files.
  • gpus Optional[Union[int, str]]: 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.
  • hostname Optional[str]: Container host name
  • interactive bool: 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.
  • ip Optional[str]: IPv4 address (e.g., 172.30.100.104)
  • ip6 Optional[str]: IPv6 address (e.g., 2001:db8::33)
  • ipc Optional[str]: IPC mode to use
  • isolation Optional[str]: Container isolation technology
  • kernel_memory Optional[Union[int, str]]: Kernel memory limit. int represents the number of bytes, but you can use "4k" or 2g for example.
  • labels Dict[str, str]: 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.
  • log_driver Optional[str]: Logging driver for the container
  • mac_address Optional[str]: Container MAC address (e.g., "92:d0:c6:0a:29:33")
  • memory Optional[Union[int, str]]: Memory limit, valid values are 1024 (ints are bytes) or "43m" or "6g".
  • memory_reservation Optional[Union[int, str]]: Memory soft limit
  • memory_swap Optional[Union[int, str]]: Swap limit equal to memory plus swap: '-1' to enable unlimited swap.
  • memory_swappiness Optional[int]: Tune container memory swappiness (0 to 100) (default -1)
  • name Optional[str]: The container name. If not provided, one is automatically genrated for you.
  • healthcheck bool: Set to False to disable container periodic healthcheck.
  • oom_kill bool: Set to False to disable the OOM killer for this container.
  • pid Optional[str]: PID namespace to use
  • pids_limit Optional[int]: Tune container pids limit (set -1 for unlimited)
  • platform Optional[str]: Set platform if server is multi-platform capable.
  • privileged bool: Give extended privileges to this container.
  • publish List[Union[Tuple[Union[str, int], Union[str, int]], Tuple[Union[str, int], Union[str, int], str]]]: 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,)].
  • publish_all bool: Publish all exposed ports to random ports.
  • read_only bool: Mount the container's root filesystem as read only.
  • restart Optional[str]: Restart policy to apply when a container exits (default "no")
  • remove bool: Automatically remove the container when it exits.
  • runtime Optional[str]: Runtime to use for this container.
  • security_options List[str]: Security options
  • shm_size Optional[Union[int, str]]: Size of /dev/shm. int is for bytes. But you can use "512m" or "4g" for example.
  • stop_timeout Optional[int]: Signal to stop a container (default "SIGTERM")
  • storage_options List[str]: Storage driver options for the container
  • tty bool: Allocate a pseudo-TTY. Allow the process to access your terminal to write on it.
  • user Optional[str]: Username or UID (format: <name|uid>[:<group|gid>])
  • userns Optional[str]: User namespace to use
  • uts Optional[str]: UTS namespace to use
  • volumes Optional[List[Union[Tuple[Union[python_on_whales.Volume, str, pathlib.Path], Union[str, pathlib.Path]], Tuple[Union[python_on_whales.Volume, str, pathlib.Path], Union[str, pathlib.Path], str]]]]: Bind mount a volume. Some examples: [("/", "/host"), ("/etc/hosts", "/etc/hosts", "rw")].
  • volume_driver Optional[str]: Optional volume driver for the container
  • workdir Optional[Union[str, pathlib.Path]]: The directory in the container where the process will be executed.

Returns

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

start

docker.container.start(containers, attach=False, stream=False)

Starts one or more stopped containers.

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

Arguments

  • containers Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or a list of containers.

stats

docker.container.stats(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.

Arguments

  • all bool: Get the stats of all containers, not just running ones.

Returns

A List[python_on_whales.ContainerStats].

stop

docker.container.stop(containers, time=None)

Stops one or more running containers

Alias: docker.stop(...)

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

Arguments

  • containers Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or a list of containers.
  • time Optional[Union[int, datetime.timedelta]]: Seconds to wait for stop before killing a container (default 10)

Raises

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

top

docker.container.top()

Get the running processes of a container

Alias: docker.top(...)

Not yet implemented

unpause

docker.container.unpause(x)

Unpause all processes within one or more containers

Alias: docker.unpause(...)

Arguments

  • x Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or more containers (name, id or python_on_whales.Container object).

Raises

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

update

docker.container.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(...)

Arguments

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

Raises

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

wait

docker.container.wait(x)

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

Alias: docker.wait(...)

Arguments

  • x Union[python_on_whales.Container, str, List[Union[python_on_whales.Container, str]]]: One or a list of containers to wait for.

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.