Skip to content

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 = 2567f0a112f6be6000cedc7d487c7af4c6489f0ceff78dd9f14e5a03a5f34877

In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2025-07-14 17:09:00.088324+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-07-14 17:09:00.105014+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:f9248aac10f2f82e0970222e36cc7b71215b88e974e001282e5cd89797a82218

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

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

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

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

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

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

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': '2567f0a112f6be6000cedc7d487c7af4c6489f0ceff78dd9f14e5a03a5f34877', 'LowerDir': '/var/lib/docker/overlay2/ff14a1e3bb2e4884ad5b71c0f4adfce013e3bd575b6cf095ece1f0eaa9502db3-init/diff:/var/lib/docker/overlay2/559d7fd4486388dd69517c0614b2af7e887a1da1aee6d441ef937399c4945b1d/diff', 'MergedDir': '/var/lib/docker/overlay2/ff14a1e3bb2e4884ad5b71c0f4adfce013e3bd575b6cf095ece1f0eaa9502db3/merged', 'UpperDir': '/var/lib/docker/overlay2/ff14a1e3bb2e4884ad5b71c0f4adfce013e3bd575b6cf095ece1f0eaa9502db3/diff', 'WorkDir': '/var/lib/docker/overlay2/ff14a1e3bb2e4884ad5b71c0f4adfce013e3bd575b6cf095ece1f0eaa9502db3/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 = 2567f0a112f6

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 = 574fc392549604f2572be685f98e3d04aebc5f7c2e47e8f83334186b3cccb2b1

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/574fc3925496

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 = 4043d6603279a6aa0ba1e7a6e94117d103a4af1b02a28b198dd155822380a498

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 = 1a:c0:58:8a:51:e8

In [151]: super_print(container.network_settings.networks)
type = <class 'dict'>, value = {'bridge': NetworkInspectResult(ipam_config=None, links=None, aliases=None, network_id='d70dfb8772f0c3df7c0c2ef7fd062a653a7113dbdeb7f8f157a484565002e9f7', endpoint_id='4043d6603279a6aa0ba1e7a6e94117d103a4af1b02a28b198dd155822380a498', 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='1a:c0:58:8a:51:e8', 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.

init

init()

Initialize this container.

See the docker.container.init command.

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.