Docker containers

Don't use the constructor directly. Instead use

from python_on_whales import docker

my_container = docker.container.inspect("my-container-name")

# for example:
if my_container.state.running:
    my_container.kill()

For type hints, use this

from python_on_whales import Container

def print_dodo(container: Container):
    print(container.execute(["echo", "dodo"]))

Attributes

It attributes are the same that you get with the command line: docker container inspect ...

If you want to know the exact structure, you can go to the docker container inspect reference page and click on "200 no error". An example is worth many lines of descriptions.

In [1]: from python_on_whales import docker

In [2]: container = docker.run("ubuntu", ["sleep", "infinity"], detach=True)

In [4]: def super_print(obj):
   ...:     print(f"type={type(obj)}, value={obj}")
   ...:

In [4]: super_print(container.id)
type = <class 'str'>, value = c6086f27fe7b8602183518be04ed0164556a0e07388cb42605573004feedb552

In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2024-04-24 08:10:23.045470+00:00

In [6]: super_print(container.path)
type = <class 'str'>, value = sleep

In [7]: super_print(container.args)
type = <class 'list'>, value = ['infinity']

In [8]: super_print(container.state.status)
type = <class 'str'>, value = running

In [9]: super_print(container.state.running)
type = <class 'bool'>, value = True

In [10]: super_print(container.state.paused)
type = <class 'bool'>, value = False

In [11]: super_print(container.state.restarting)
type = <class 'bool'>, value = False

In [12]: super_print(container.state.oom_killed)
type = <class 'bool'>, value = False

In [13]: super_print(container.state.dead)
type = <class 'bool'>, value = False

In [14]: super_print(container.state.pid)
type = <class 'int'>, value = 2689

In [15]: super_print(container.state.exit_code)
type = <class 'int'>, value = 0

In [16]: super_print(container.state.error)
type = <class 'str'>, value = 

In [17]: super_print(container.state.started_at)
type = <class 'datetime.datetime'>, value = 2024-04-24 08:10:23.226303+00:00

In [18]: super_print(container.state.finished_at)
type = <class 'datetime.datetime'>, value = 0001-01-01 00:00:00+00:00

In [19]: super_print(container.state.health)
type = <class 'NoneType'>, value = None

In [20]: super_print(container.image)
type = <class 'str'>, value = sha256:7af9ba4f0a47d9bc8b1ffa492c6b0276476f1889cf4e699fba2236924e5932ed

In [21]: super_print(container.resolv_conf_path)
type = <class 'str'>, value = /var/lib/docker/containers/c6086f27fe7b8602183518be04ed0164556a0e07388cb42605573004feedb552/resolv.conf

In [22]: super_print(container.hostname_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/c6086f27fe7b8602183518be04ed0164556a0e07388cb42605573004feedb552/hostname

In [23]: super_print(container.hosts_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/c6086f27fe7b8602183518be04ed0164556a0e07388cb42605573004feedb552/hosts

In [24]: super_print(container.log_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/c6086f27fe7b8602183518be04ed0164556a0e07388cb42605573004feedb552/c6086f27fe7b8602183518be04ed0164556a0e07388cb42605573004feedb552-json.log

In [25]: super_print(container.node)
type = <class 'NoneType'>, value = None

In [26]: super_print(container.name)
type = <class 'str'>, value = jolly_mendel

In [27]: super_print(container.restart_count)
type = <class 'int'>, value = 0

In [28]: super_print(container.driver)
type = <class 'str'>, value = overlay2

In [29]: super_print(container.platform)
type = <class 'str'>, value = linux

In [30]: super_print(container.mount_label)
type = <class 'str'>, value = 

In [31]: super_print(container.process_label)
type = <class 'str'>, value = 

In [32]: super_print(container.app_armor_profile)
type = <class 'str'>, value = docker-default

In [33]: super_print(container.exec_ids)
type = <class 'NoneType'>, value = None

In [34]: super_print(container.host_config.cpu_shares)
type = <class 'int'>, value = 0

In [35]: super_print(container.host_config.memory)
type = <class 'int'>, value = 0

In [36]: super_print(container.host_config.cgroup_parent)
type = <class 'pathlib.PosixPath'>, value = .

In [37]: super_print(container.host_config.blkio_weight)
type = <class 'int'>, value = 0

In [38]: super_print(container.host_config.blkio_weight_device)
type = <class 'list'>, value = []

In [39]: super_print(container.host_config.blkio_device_read_bps)
type = <class 'list'>, value = []

In [40]: super_print(container.host_config.blkio_device_write_bps)
type = <class 'list'>, value = []

In [41]: super_print(container.host_config.blkio_device_read_iops)
type = <class 'list'>, value = []

In [42]: super_print(container.host_config.blkio_device_write_iops)
type = <class 'list'>, value = []

In [43]: super_print(container.host_config.cpu_period)
type = <class 'int'>, value = 0

In [44]: super_print(container.host_config.cpu_quota)
type = <class 'int'>, value = 0

In [45]: super_print(container.host_config.cpu_realtime_period)
type = <class 'int'>, value = 0

In [46]: super_print(container.host_config.cpu_realtime_runtime)
type = <class 'int'>, value = 0

In [47]: super_print(container.host_config.cpuset_cpus)
type = <class 'str'>, value = 

In [48]: super_print(container.host_config.cpuset_mems)
type = <class 'str'>, value = 

In [49]: super_print(container.host_config.devices)
type = <class 'list'>, value = []

In [50]: super_print(container.host_config.device_cgroup_rules)
type = <class 'NoneType'>, value = None

In [51]: super_print(container.host_config.device_requests)
type = <class 'NoneType'>, value = None

In [52]: super_print(container.host_config.kernel_memory)
type = <class 'NoneType'>, value = None

In [53]: super_print(container.host_config.kernel_memory_tcp)
type = <class 'NoneType'>, value = None

In [54]: super_print(container.host_config.memory_reservation)
type = <class 'int'>, value = 0

In [55]: super_print(container.host_config.memory_swap)
type = <class 'int'>, value = 0

In [56]: super_print(container.host_config.memory_swappiness)
type = <class 'NoneType'>, value = None

In [57]: super_print(container.host_config.nano_cpus)
type = <class 'int'>, value = 0

In [58]: super_print(container.host_config.oom_kill_disable)
type = <class 'NoneType'>, value = None

In [59]: super_print(container.host_config.init)
type = <class 'NoneType'>, value = None

In [60]: super_print(container.host_config.pids_limit)
type = <class 'NoneType'>, value = None

In [61]: super_print(container.host_config.ulimits)
type = <class 'NoneType'>, value = None

In [62]: super_print(container.host_config.cpu_count)
type = <class 'int'>, value = 0

In [63]: super_print(container.host_config.cpu_percent)
type = <class 'int'>, value = 0

In [64]: super_print(container.host_config.binds)
type = <class 'NoneType'>, value = None

In [65]: super_print(container.host_config.container_id_file)
type = <class 'pathlib.PosixPath'>, value = .

In [66]: super_print(container.host_config.log_config.type)
type = <class 'str'>, value = json-file

In [67]: super_print(container.host_config.log_config.config)
type = <class 'dict'>, value = {}

In [68]: super_print(container.host_config.network_mode)
type = <class 'str'>, value = default

In [69]: super_print(container.host_config.port_bindings)
type = <class 'dict'>, value = {}

In [70]: super_print(container.host_config.restart_policy.name)
type = <class 'str'>, value = no

In [71]: super_print(container.host_config.restart_policy.maximum_retry_count)
type = <class 'int'>, value = 0

In [72]: super_print(container.host_config.auto_remove)
type = <class 'bool'>, value = False

In [73]: super_print(container.host_config.volume_driver)
type = <class 'str'>, value = 

In [74]: super_print(container.host_config.volumes_from)
type = <class 'NoneType'>, value = None

In [75]: super_print(container.host_config.mounts)
type = <class 'NoneType'>, value = None

In [76]: super_print(container.host_config.capabilities)
type = <class 'NoneType'>, value = None

In [77]: super_print(container.host_config.cap_add)
type = <class 'NoneType'>, value = None

In [78]: super_print(container.host_config.cap_drop)
type = <class 'NoneType'>, value = None

In [79]: super_print(container.host_config.dns)
type = <class 'list'>, value = []

In [80]: super_print(container.host_config.dns_options)
type = <class 'list'>, value = []

In [81]: super_print(container.host_config.dns_search)
type = <class 'list'>, value = []

In [82]: super_print(container.host_config.extra_hosts)
type = <class 'NoneType'>, value = None

In [83]: super_print(container.host_config.group_add)
type = <class 'NoneType'>, value = None

In [84]: super_print(container.host_config.ipc_mode)
type = <class 'str'>, value = private

In [85]: super_print(container.host_config.cgroup)
type = <class 'str'>, value = 

In [86]: super_print(container.host_config.links)
type = <class 'NoneType'>, value = None

In [87]: super_print(container.host_config.oom_score_adj)
type = <class 'int'>, value = 0

In [88]: super_print(container.host_config.pid_mode)
type = <class 'str'>, value = 

In [89]: super_print(container.host_config.privileged)
type = <class 'bool'>, value = False

In [90]: super_print(container.host_config.publish_all_ports)
type = <class 'bool'>, value = False

In [91]: super_print(container.host_config.readonly_rootfs)
type = <class 'bool'>, value = False

In [92]: super_print(container.host_config.security_opt)
type = <class 'NoneType'>, value = None

In [93]: super_print(container.host_config.storage_opt)
type = <class 'NoneType'>, value = None

In [94]: super_print(container.host_config.tmpfs)
type = <class 'NoneType'>, value = None

In [95]: super_print(container.host_config.uts_mode)
type = <class 'str'>, value = 

In [96]: super_print(container.host_config.userns_mode)
type = <class 'str'>, value = 

In [97]: super_print(container.host_config.shm_size)
type = <class 'int'>, value = 67108864

In [98]: super_print(container.host_config.sysctls)
type = <class 'NoneType'>, value = None

In [99]: super_print(container.host_config.runtime)
type = <class 'str'>, value = runc

In [100]: super_print(container.host_config.console_size)
type = <class 'tuple'>, value = (0, 0)

In [101]: super_print(container.host_config.isolation)
type = <class 'str'>, value = 

In [102]: super_print(container.host_config.masked_paths)
type = <class 'list'>, value = [PosixPath('/proc/asound'), PosixPath('/proc/acpi'), PosixPath('/proc/kcore'), PosixPath('/proc/keys'), PosixPath('/proc/latency_stats'), PosixPath('/proc/timer_list'), PosixPath('/proc/timer_stats'), PosixPath('/proc/sched_debug'), PosixPath('/proc/scsi'), PosixPath('/sys/firmware'), PosixPath('/sys/devices/virtual/powercap')]

In [103]: super_print(container.host_config.readonly_paths)
type = <class 'list'>, value = [PosixPath('/proc/bus'), PosixPath('/proc/fs'), PosixPath('/proc/irq'), PosixPath('/proc/sys'), PosixPath('/proc/sysrq-trigger')]

In [104]: super_print(container.graph_driver.name)
type = <class 'str'>, value = overlay2

In [105]: super_print(container.graph_driver.data)
type = <class 'dict'>, value = {'LowerDir': '/var/lib/docker/overlay2/531d31c773d71597167efb136940c333ad732bd3cb375d0d8b250d33ece0d530-init/diff:/var/lib/docker/overlay2/b3b19c7c96cc5a83a148b4544e513359044e52af650bf47d3cb4adda9927cd4b/diff', 'MergedDir': '/var/lib/docker/overlay2/531d31c773d71597167efb136940c333ad732bd3cb375d0d8b250d33ece0d530/merged', 'UpperDir': '/var/lib/docker/overlay2/531d31c773d71597167efb136940c333ad732bd3cb375d0d8b250d33ece0d530/diff', 'WorkDir': '/var/lib/docker/overlay2/531d31c773d71597167efb136940c333ad732bd3cb375d0d8b250d33ece0d530/work'}

In [106]: super_print(container.size_rw)
type = <class 'NoneType'>, value = None

In [107]: super_print(container.size_root_fs)
type = <class 'NoneType'>, value = None

In [108]: super_print(container.mounts)
type = <class 'list'>, value = []

In [109]: super_print(container.config.hostname)
type = <class 'str'>, value = c6086f27fe7b

In [110]: super_print(container.config.domainname)
type = <class 'str'>, value = 

In [111]: super_print(container.config.user)
type = <class 'str'>, value = 

In [112]: super_print(container.config.attach_stdin)
type = <class 'bool'>, value = False

In [113]: super_print(container.config.attach_stdout)
type = <class 'bool'>, value = False

In [114]: super_print(container.config.attach_stderr)
type = <class 'bool'>, value = False

In [115]: super_print(container.config.exposed_ports)
type = <class 'NoneType'>, value = None

In [116]: super_print(container.config.tty)
type = <class 'bool'>, value = False

In [117]: super_print(container.config.open_stdin)
type = <class 'bool'>, value = False

In [118]: super_print(container.config.stdin_once)
type = <class 'bool'>, value = False

In [119]: super_print(container.config.env)
type = <class 'list'>, value = ['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin']

In [120]: super_print(container.config.cmd)
type = <class 'list'>, value = ['sleep', 'infinity']

In [121]: super_print(container.config.healthcheck)
type = <class 'NoneType'>, value = None

In [122]: super_print(container.config.args_escaped)
type = <class 'NoneType'>, value = None

In [123]: super_print(container.config.image)
type = <class 'str'>, value = ubuntu

In [124]: super_print(container.config.volumes)
type = <class 'NoneType'>, value = None

In [125]: super_print(container.config.working_dir)
type = <class 'pathlib.PosixPath'>, value = .

In [126]: super_print(container.config.entrypoint)
type = <class 'NoneType'>, value = None

In [127]: super_print(container.config.network_disabled)
type = <class 'NoneType'>, value = None

In [128]: super_print(container.config.mac_address)
type = <class 'NoneType'>, value = None

In [129]: super_print(container.config.on_build)
type = <class 'NoneType'>, value = None

In [130]: super_print(container.config.labels)
type = <class 'dict'>, value = {'org.opencontainers.image.ref.name': 'ubuntu', 'org.opencontainers.image.version': '22.04'}

In [131]: super_print(container.config.stop_signal)
type = <class 'NoneType'>, value = None

In [132]: super_print(container.config.stop_timeout)
type = <class 'NoneType'>, value = None

In [133]: super_print(container.config.shell)
type = <class 'NoneType'>, value = None

In [134]: super_print(container.network_settings.bridge)
type = <class 'str'>, value = 

In [135]: super_print(container.network_settings.sandbox_id)
type = <class 'str'>, value = e602b047c4edf6297c454f5274130c89980a02b1224a764369da55d2f2c39aa0

In [136]: super_print(container.network_settings.hairpin_mode)
type = <class 'bool'>, value = False

In [137]: super_print(container.network_settings.link_local_ipv6_address)
type = <class 'str'>, value = 

In [138]: super_print(container.network_settings.link_local_ipv6_prefix_length)
type = <class 'int'>, value = 0

In [139]: super_print(container.network_settings.ports)
type = <class 'dict'>, value = {}

In [140]: super_print(container.network_settings.sandbox_key)
type = <class 'pathlib.PosixPath'>, value = /var/run/docker/netns/e602b047c4ed

In [141]: super_print(container.network_settings.secondary_ip_addresses)
type = <class 'NoneType'>, value = None

In [142]: super_print(container.network_settings.secondary_ipv6_addresses)
type = <class 'NoneType'>, value = None

In [143]: super_print(container.network_settings.endpoint_id)
type = <class 'str'>, value = 9121bf89004d9153a7e56ee27e7a7c3729b61d904856e39da74473c777063be0

In [144]: super_print(container.network_settings.gateway)
type = <class 'str'>, value = 172.17.0.1

In [145]: super_print(container.network_settings.global_ipv6_address)
type = <class 'str'>, value = 

In [146]: super_print(container.network_settings.global_ipv6_prefix_length)
type = <class 'int'>, value = 0

In [147]: super_print(container.network_settings.ip_address)
type = <class 'str'>, value = 172.17.0.2

In [148]: super_print(container.network_settings.ip_prefix_length)
type = <class 'int'>, value = 16

In [149]: super_print(container.network_settings.ipv6_gateway)
type = <class 'str'>, value = 

In [150]: super_print(container.network_settings.mac_address)
type = <class 'str'>, value = 02:42:ac:11:00:02

In [151]: super_print(container.network_settings.networks)
type = <class 'dict'>, value = {'bridge': NetworkInspectResult(ipam_config=None, links=None, aliases=None, network_id='f9eb4c0766a078ef1aa0b80f7777b84b58e96f4dd84040829f0eaff071634772', endpoint_id='9121bf89004d9153a7e56ee27e7a7c3729b61d904856e39da74473c777063be0', gateway='172.17.0.1', ip_address='172.17.0.2', ip_prefix_length=16, ipv6_gateway='', global_ipv6_address='', global_ipv6_prefix_length=0, mac_address='02:42:ac:11:00:02', driver_options=None)}

Methods

Container

attach

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

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

Alias: docker.attach(...)

See the docker.container.attach command for information about the arguments.

commit

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

Create a new image from the container's changes.

Alias: docker.commit(...)

See the docker.container.commit command for information about the arguments.

diff

diff()

Returns the diff of this container filesystem.

See the docker.container.diff command for information about the arguments.

execute

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

Execute a command in this container

See the docker.container.execute command for information about the arguments.

exists

exists()

Returns True if the docker container exists and False if it doesn't exists.

If it doesn't exists, it most likely mean that it was removed.

See the docker.container.exists command for information about the arguments.

export

export(output)

Export this container filesystem.

See the docker.container.export command for information about the arguments.

kill

kill(signal=None)

Kill this container

See the docker.container.kill command for information about the arguments.

logs

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

Returns the logs of the container

See the docker.container.logs command for information about the arguments.

pause

pause()

Pause this container.

See the docker.container.pause command for information about the arguments.

remove

remove(force=False, volumes=False)

Remove this container.

See the docker.container.remove command for information about the arguments.

rename

rename(new_name)

Rename this container

See the docker.container.rename command for information about the arguments.

restart

restart(time=None)

Restarts this container.

See the docker.container.restart command for information about the arguments.

start

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

Starts this container.

See the docker.container.start command for information about the arguments.

stop

stop(time=None)

Stops this container.

See the docker.container.stop command for information about the arguments.

unpause

unpause()

Unpause the container

See the docker.container.unpause command for information about the arguments.