Skip to content

Docker images

Don't use the constructor directly. Instead use 

from python_on_whales import docker

my_docker_image = docker.image.inspect("my-image-name")

# or

my_docker_image = docker.pull("my-image-name")

For type hints, use this

from python_on_whales import docker, Image

def print_dodo(image: Image):
    print(docker.run(image, ["echo", "dodo"]))

Attributes

It attributes are the same that you get with the command line: docker image inspect ...

To get a complete description of those attributes, you can take a look at the daemon api 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]: image = docker.pull("ubuntu")
20.04: Pulling from library/ubuntu
6a5697faee43: Pull complete
ba13d3bc422b: Pull complete
a254829d9e55: Pull complete
Digest: sha256:fff16eea1a8ae92867721d90c59a75652ea66d29c05294e6e2f898704bdb8cf1
Status: Downloaded newer image for ubuntu:latest
docker.io/library/ubuntu:latest

In [3]: def super_print(obj):
   ...:     print(f"type={type(obj)}, value={obj}")
   ...:

In [4]: super_print(image.id)
type = <class 'str'>, value = sha256:7af9ba4f0a47d9bc8b1ffa492c6b0276476f1889cf4e699fba2236924e5932ed

In [5]: super_print(image.repo_tags)
type = <class 'list'>, value = ['ubuntu:latest']

In [6]: super_print(image.repo_digests)
type = <class 'list'>, value = ['ubuntu@sha256:1b8d8ff4777f36f19bfe73ee4df61e3a0b789caeff29caa019539ec7c9a57f95']

In [7]: super_print(image.parent)
type = <class 'str'>, value = 

In [8]: super_print(image.comment)
type = <class 'str'>, value = 

In [9]: super_print(image.created)
type = <class 'datetime.datetime'>, value = 2024-04-10 18:52:04.937319+00:00

In [10]: super_print(image.container)
type = <class 'str'>, value = 631d67c0ae0cd79f55f653982ce9403eeb5616ba0c608defcb170e13713a28c5

In [11]: super_print(image.container_config)
type = <class 'python_on_whales.components.container.models.ContainerConfig'>, value = hostname='631d67c0ae0c' domainname='' user='' attach_stdin=False attach_stdout=False attach_stderr=False exposed_ports=None tty=False open_stdin=False stdin_once=False env=['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'] cmd=['/bin/sh', '-c', '#(nop) ', 'CMD ["/bin/bash"]'] healthcheck=None args_escaped=None image='sha256:fe8e68547ff6adf77f3cf753afd0510ccad3836cd96b6fe167e92ec84756d66e' volumes=None working_dir=PosixPath('.') entrypoint=None network_disabled=None mac_address=None on_build=None labels={'org.opencontainers.image.ref.name': 'ubuntu', 'org.opencontainers.image.version': '22.04'} stop_signal=None stop_timeout=None shell=None systemd_mode=None

In [12]: super_print(image.docker_version)
type = <class 'str'>, value = 24.0.5

In [13]: super_print(image.author)
type = <class 'str'>, value = 

In [14]: super_print(image.config)
type = <class 'python_on_whales.components.container.models.ContainerConfig'>, value = hostname='' domainname='' user='' attach_stdin=False attach_stdout=False attach_stderr=False exposed_ports=None tty=False open_stdin=False stdin_once=False env=['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'] cmd=['/bin/bash'] healthcheck=None args_escaped=None image='sha256:fe8e68547ff6adf77f3cf753afd0510ccad3836cd96b6fe167e92ec84756d66e' volumes=None working_dir=PosixPath('.') entrypoint=None network_disabled=None mac_address=None on_build=None labels={'org.opencontainers.image.ref.name': 'ubuntu', 'org.opencontainers.image.version': '22.04'} stop_signal=None stop_timeout=None shell=None systemd_mode=None

In [15]: super_print(image.architecture)
type = <class 'str'>, value = amd64

In [16]: super_print(image.os)
type = <class 'str'>, value = linux

In [17]: super_print(image.os_version)
type = <class 'NoneType'>, value = None

In [18]: super_print(image.size)
type = <class 'int'>, value = 77859326

In [19]: super_print(image.virtual_size)
type = <class 'int'>, value = 77859326

In [20]: super_print(image.graph_driver.name)
type = <class 'str'>, value = overlay2

In [21]: super_print(image.graph_driver.data)
type = <class 'dict'>, value = {'MergedDir': '/var/lib/docker/overlay2/b3b19c7c96cc5a83a148b4544e513359044e52af650bf47d3cb4adda9927cd4b/merged', 'UpperDir': '/var/lib/docker/overlay2/b3b19c7c96cc5a83a148b4544e513359044e52af650bf47d3cb4adda9927cd4b/diff', 'WorkDir': '/var/lib/docker/overlay2/b3b19c7c96cc5a83a148b4544e513359044e52af650bf47d3cb4adda9927cd4b/work'}

In [22]: super_print(image.root_fs.type)
type = <class 'str'>, value = layers

In [23]: super_print(image.root_fs.layers)
type = <class 'list'>, value = ['sha256:e0a9f5911802534ba097660206feabeb0247a81e409029167b30e2e1f2803b57']

In [24]: super_print(image.root_fs.base_layer)
type = <class 'NoneType'>, value = None

In [25]: super_print(image.metadata)
type = <class 'dict'>, value = {'LastTagTime': '0001-01-01T00:00:00Z'}

Methods

Image

copy_from 

copy_from(path_in_image, destination, pull='missing')

Copy a file from a docker image in the local filesystem.

See the docker.image.copy_from command for information about the arguments.

copy_to 

copy_to(local_path, path_in_image, new_tag=None, pull='missing')

Copy a file from the local filesystem in a docker image to create a new docker image.

As if you did a dockerfile with a COPY instruction.

See the docker.image.copy_to command for information about the arguments.

exists 

exists()

Returns True if the docker image exists and False if it doesn't exists.

Note that you might have done docker.image.remove("some_tag") and the image might still exists because python-on-whales references images by id, not by tag.

See the docker.image.exists command for information about the arguments.

remove 

remove(force=False, prune=True)

Remove this Docker image.

See the docker.image.remove command for information about the arguments.

save 

save(output=None)

Saves this Docker image in a tar.

See the docker.image.save command for information about the arguments.

tag 

tag(new_tag)

Add a tag to a Docker image.

See the docker.image.tag command for information about the arguments.