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 = 1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958
In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2026-01-10 18:01:17.926936+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 = 2988
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-01-10 18:01:17.943432+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:c3a134f2ace4f6d480733efcfef27c60ea8ed48be1cd36f2c17ec0729775b2c8
In [21]: super_print(container.resolv_conf_path)
type = <class 'str'>, value = /var/lib/docker/containers/1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958/resolv.conf
In [22]: super_print(container.hostname_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958/hostname
In [23]: super_print(container.hosts_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958/hosts
In [24]: super_print(container.log_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958/1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958-json.log
In [25]: super_print(container.node)
type = <class 'NoneType'>, value = None
In [26]: super_print(container.name)
type = <class 'str'>, value = inspiring_kepler
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': '1630696d5602099b60584f20c5efba9e8bbe0cbb001514fddbda5be6d3dcf958', 'LowerDir': '/var/lib/docker/overlay2/2a94fed82b90ea4c93da82528d6b3d93994120727eff23e374fd9da50bec11e1-init/diff:/var/lib/docker/overlay2/3786069d7460046b721dbac179aad0e4008a56d56f80d5ab07b4ef47559497bf/diff', 'MergedDir': '/var/lib/docker/overlay2/2a94fed82b90ea4c93da82528d6b3d93994120727eff23e374fd9da50bec11e1/merged', 'UpperDir': '/var/lib/docker/overlay2/2a94fed82b90ea4c93da82528d6b3d93994120727eff23e374fd9da50bec11e1/diff', 'WorkDir': '/var/lib/docker/overlay2/2a94fed82b90ea4c93da82528d6b3d93994120727eff23e374fd9da50bec11e1/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 = 1630696d5602
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 = a75d2036fddbaca78dcc79ab388d40aa356db2eee6485df63d4833fa595fbea0
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/a75d2036fddb
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 = 02b3353cc3e6c6830cbf402ef6095764593067cfdbafa11fcf6bbce51c256447
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 = ea:18:6b:c3:f3:94
In [151]: super_print(container.network_settings.networks)
type = <class 'dict'>, value = {'bridge': NetworkInspectResult(ipam_config=None, links=None, aliases=None, network_id='16444f2550bdc799ca4b22992d385067763ef5ab7d5b72eeb4dbd754482a9572', endpoint_id='02b3353cc3e6c6830cbf402ef6095764593067cfdbafa11fcf6bbce51c256447', 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='ea:18:6b:c3:f3:94', 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.