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()
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 = bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663
In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2026-03-09 14:17:52.224712+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 = 3206
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 = 2026-03-09 14:17:52.242698+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:bbdabce66f1b7dde0c081a6b4536d837cd81dd322dd8c99edd68860baf3b2db3
In [21]: super_print(container.resolv_conf_path)
type = <class 'str'>, value = /var/lib/docker/containers/bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663/resolv.conf
In [22]: super_print(container.hostname_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663/hostname
In [23]: super_print(container.hosts_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663/hosts
In [24]: super_print(container.log_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663/bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663-json.log
In [25]: super_print(container.node)
type = <class 'NoneType'>, value = None
In [26]: super_print(container.name)
type = <class 'str'>, value = unruffled_mcnulty
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 'list'>, value = []
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 = bridge
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/interrupts'), 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 = {'ID': 'bcde54a1aa8ff9ef895fd5622903de6fdac5369643585de04f50a8ea77682663', 'LowerDir': '/var/lib/docker/overlay2/09ad3c71c75e5e4dc3e0f810c40e76a88f484cf0b660632d5130362ad56d3965-init/diff:/var/lib/docker/overlay2/044e4510aad1f9dc9587beda8b261b1dd325d066120d9cefd43f8c6303d1be2e/diff', 'MergedDir': '/var/lib/docker/overlay2/09ad3c71c75e5e4dc3e0f810c40e76a88f484cf0b660632d5130362ad56d3965/merged', 'UpperDir': '/var/lib/docker/overlay2/09ad3c71c75e5e4dc3e0f810c40e76a88f484cf0b660632d5130362ad56d3965/diff', 'WorkDir': '/var/lib/docker/overlay2/09ad3c71c75e5e4dc3e0f810c40e76a88f484cf0b660632d5130362ad56d3965/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 = bcde54a1aa8f
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': '24.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 = a1f44ecde63c4bd2e055fa243bb3a0319a427ffceb29ca7231826a9ab83711d9
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/a1f44ecde63c
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 = c5b2f3029c50436eb4d455623d65e3f24fc4ec230315884e80b32d1fe40417cf
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 = 0a:b1:01:d4:11:3a
In [151]: super_print(container.network_settings.networks)
type = <class 'dict'>, value = {'bridge': NetworkInspectResult(ipam_config=None, links=None, aliases=None, network_id='eabe061a260dd729b83ab1a2b80e38743550db5dc6ebef1dce5b1e3719c9ffc6', endpoint_id='c5b2f3029c50436eb4d455623d65e3f24fc4ec230315884e80b32d1fe40417cf', 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='0a:b1:01:d4:11:3a', 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.