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:97bed23a34971024aa8d254abbe67b7168772340d1f494034773bc464e8dd5b6

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:66460d557b25769b102175144d538d88219c077c678a49af4afca6fbfc1b5252']

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 = 2025-10-01 13:01:37.838375+00:00

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

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

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

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:23fd913d7c4cf84a6e1172185a7b36958f2b8b84fedafff8fc952b31c9cb161f' 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': '24.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 = 78119250

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

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/6d443b7b284336ff3c1d0b3bc57495640f141533ee08417335e2437d821ef305/merged', 'UpperDir': '/var/lib/docker/overlay2/6d443b7b284336ff3c1d0b3bc57495640f141533ee08417335e2437d821ef305/diff', 'WorkDir': '/var/lib/docker/overlay2/6d443b7b284336ff3c1d0b3bc57495640f141533ee08417335e2437d821ef305/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:073ec47a8c22dcaa4d6e5758799ccefe2f9bde943685830b1bf6fd2395f5eabc']

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.