SystemCLI

disk_free

disk_free()

Give information about the disk usage of the Docker daemon.

Returns a python_on_whales.DiskFreeResult object.

from python_on_whales import docker
disk_free_result = docker.system.disk_free()
print(disk_free_result.images.active)  #int
print(disk_free_result.containers.reclaimable)  # int, number of bytes
print(disk_free_result.volumes.reclaimable_percent)  # float
print(disk_free_result.build_cache.total_count)  # int
print(disk_free_result.build_cache.size)  # int, number of bytes
...

Note that the number are not 100% accurate because the docker CLI doesn't provide the exact numbers.

Maybe in a future implementation, we can provide exact numbers.

Verbose mode is not yet implemented.

events

events(since=None, until=None, filters={})

Return docker events information up to the current point in time.

If until is not specified, then the iterator returned is infinite. For example

from python_on_whales import docker
from datetime import datetime, timedelta


for event in docker.system.events():
    print("new event!")
    print(event)
    # this will never end, that's ok if you want to monitor something
    # for a long time. You can also use 'break' in the for loop if needed.

for event in docker.system.events(until=datetime.now() - timedelta(seconds=30)):
    print("some past event")
    print(event)
    # this loop will end, unlike the previous one

for event in docker.system.events(until=datetime.now() + timedelta(seconds=30)):
    print("some past event")
    print(event)
    # this loop will end in 30 seconds, even if there are no events at all

events = list(docker.system.events(filters={"container": "mycontainer"}, until=datetime.now()))
# the list of all events concerning the container "mycontainer"

Parameters:

Name	Type	Description	Default
since	Union[None, datetime.datetime, datetime.timedelta]	Show all events created since timestamp	None
until	Union[None, datetime.datetime, datetime.timedelta]	Stream events until this timestamp	None
filters	Dict[str, str]	See the Docker documentation page about filtering .	{}

Returns

A iterator which will yield DockerEvent objects from stdout/stderr

reference page for system events

info

info()

Returns diverse information about the Docker client and daemon.

Returns

A `python_on_whales.SystemInfo` object

As an example

from python_on_whales import docker

info = docker.system.info()
print(info.images)
# 40
print(info.plugins.volume)
# ["local"}
...

You can find all attributes available by looking up the reference page for system info.

prune

prune(all=False, volumes=False, filters={})

Remove unused docker data

Parameters:

Name	Type	Description	Default
all	bool	Remove all unused images not just dangling ones	False
volumes	bool	Prune volumes	False
filters	Dict[str, str]	See the Docker documentation page about filtering . For example, filters=dict(until="24h").	{}