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 = 8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9
In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2025-10-24 09:07:30.635402+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 = 2993
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 = 2025-10-24 09:07:30.656720+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:97bed23a34971024aa8d254abbe67b7168772340d1f494034773bc464e8dd5b6
In [21]: super_print(container.resolv_conf_path)
type = <class 'str'>, value = /var/lib/docker/containers/8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9/resolv.conf
In [22]: super_print(container.hostname_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9/hostname
In [23]: super_print(container.hosts_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9/hosts
In [24]: super_print(container.log_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9/8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9-json.log
In [25]: super_print(container.node)
type = <class 'NoneType'>, value = None
In [26]: super_print(container.name)
type = <class 'str'>, value = charming_albattani
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': '8e0370255fc545f41e064b070c6a8c108341e31f3773203b3d33699d423897b9', 'LowerDir': '/var/lib/docker/overlay2/c556adbb78e86bb1f88c7d36679185019b6f4a49c45d5d4fd2e01a8967912d94-init/diff:/var/lib/docker/overlay2/6d443b7b284336ff3c1d0b3bc57495640f141533ee08417335e2437d821ef305/diff', 'MergedDir': '/var/lib/docker/overlay2/c556adbb78e86bb1f88c7d36679185019b6f4a49c45d5d4fd2e01a8967912d94/merged', 'UpperDir': '/var/lib/docker/overlay2/c556adbb78e86bb1f88c7d36679185019b6f4a49c45d5d4fd2e01a8967912d94/diff', 'WorkDir': '/var/lib/docker/overlay2/c556adbb78e86bb1f88c7d36679185019b6f4a49c45d5d4fd2e01a8967912d94/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 = 8e0370255fc5
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 = b6afee97a97ade49f273320da640d2b83d591ebbc9881367c4e82b91ec3d5ec6
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/b6afee97a97a
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 = 0e26168ace0942e4dfe10606cdf8a78b3a00d0374c5cefa10b50a47ff30f0127
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 = 2e:43:6c:c6:ca:dd
In [151]: super_print(container.network_settings.networks)
type = <class 'dict'>, value = {'bridge': NetworkInspectResult(ipam_config=None, links=None, aliases=None, network_id='f24822db0aaaeb9d49ce8fdb805e40d2b2de98fd0c31e431982dbe023abc3d39', endpoint_id='0e26168ace0942e4dfe10606cdf8a78b3a00d0374c5cefa10b50a47ff30f0127', 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='2e:43:6c:c6:ca:dd', 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.