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 = 3c3d7c334a1ef958e47623e6f937e75d05de108ea849899b76dc2161267912a9
In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2025-01-10 19:27:06.308432+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 = 2811
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-01-10 19:27:06.479728+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:b1d9df8ab81559494794e522b380878cf9ba82d4c1fb67293bcf931c3aa69ae4
In [21]: super_print(container.resolv_conf_path)
type = <class 'str'>, value = /var/lib/docker/containers/3c3d7c334a1ef958e47623e6f937e75d05de108ea849899b76dc2161267912a9/resolv.conf
In [22]: super_print(container.hostname_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/3c3d7c334a1ef958e47623e6f937e75d05de108ea849899b76dc2161267912a9/hostname
In [23]: super_print(container.hosts_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/3c3d7c334a1ef958e47623e6f937e75d05de108ea849899b76dc2161267912a9/hosts
In [24]: super_print(container.log_path)
type = <class 'pathlib.PosixPath'>, value = /var/lib/docker/containers/3c3d7c334a1ef958e47623e6f937e75d05de108ea849899b76dc2161267912a9/3c3d7c334a1ef958e47623e6f937e75d05de108ea849899b76dc2161267912a9-json.log
In [25]: super_print(container.node)
type = <class 'NoneType'>, value = None
In [26]: super_print(container.name)
type = <class 'str'>, value = eager_mayer
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/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/0ce753a547927c5ddd31f3e9b850ddf2ad2715744104602504185a712bf19e99-init/diff:/var/lib/docker/overlay2/72efcd8391714be72ebc986a431f225af551cdd524b173746fe069c7256d7fcd/diff', 'MergedDir': '/var/lib/docker/overlay2/0ce753a547927c5ddd31f3e9b850ddf2ad2715744104602504185a712bf19e99/merged', 'UpperDir': '/var/lib/docker/overlay2/0ce753a547927c5ddd31f3e9b850ddf2ad2715744104602504185a712bf19e99/diff', 'WorkDir': '/var/lib/docker/overlay2/0ce753a547927c5ddd31f3e9b850ddf2ad2715744104602504185a712bf19e99/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 = 3c3d7c334a1e
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 = 7dd1e29cd8e485b9a337f5897050df889e12f638cf16116fc44821be77b76b13
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/7dd1e29cd8e4
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 = 53ce975426ed541d3bb6bdf60bcbff68238aecd9da7f4b3e1114e0fa0bc5eaee
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='5f32aa3f3a886ea8dce9734435dac4126539d4318f1f9dfaf20221d1a8b67508', endpoint_id='53ce975426ed541d3bb6bdf60bcbff68238aecd9da7f4b3e1114e0fa0bc5eaee', 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.