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 = 79ab867c8d7930d82b9c4fa0b7d23987be909a957b09776cfff928bfa7a3f47a

In [5]: super_print(container.created)
type = <class 'datetime.datetime'>, value = 2025-03-27 11:16:37.866740+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 = 2806

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-03-27 11:16:38.030625+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:a04dc4851cbcbb42b54d1f52a41f5f9eca6a5fd03748c3f6eb2cbeb238ca99bd

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

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

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

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

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

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

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/65d88cf04ec92f79457c302a1cda87192d0afc43e283d5cf18a7853cf4f1f868-init/diff:/var/lib/docker/overlay2/24a0976a392026ec49c4f2fd855ac9133f1956336f01236f1de2bcfe2cbf1d1d/diff', 'MergedDir': '/var/lib/docker/overlay2/65d88cf04ec92f79457c302a1cda87192d0afc43e283d5cf18a7853cf4f1f868/merged', 'UpperDir': '/var/lib/docker/overlay2/65d88cf04ec92f79457c302a1cda87192d0afc43e283d5cf18a7853cf4f1f868/diff', 'WorkDir': '/var/lib/docker/overlay2/65d88cf04ec92f79457c302a1cda87192d0afc43e283d5cf18a7853cf4f1f868/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 = 79ab867c8d79

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 = 7aa48cbace04e2cbdaf878b2cdef3dbbc2a9e6f75d3d38b66717e9e2b9fdff2f

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/7aa48cbace04

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 = a333def842decf98b63178da333621b131d8687b90d76714761320affcb0389c

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='8086bab794df227dfea3c6f9f9bc22421a796776f2f8c64536dc88a69a729661', endpoint_id='a333def842decf98b63178da333621b131d8687b90d76714761320affcb0389c', 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.

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.