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:a04dc4851cbcbb42b54d1f52a41f5f9eca6a5fd03748c3f6eb2cbeb238ca99bd

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:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782']

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-01-27 04:14:03.599776+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 = 24.0.7

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:807964e308294a3fd3ce42968625699bece61632bd5ce017acb6654314347f9c' 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 = 78127075

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/24a0976a392026ec49c4f2fd855ac9133f1956336f01236f1de2bcfe2cbf1d1d/merged', 'UpperDir': '/var/lib/docker/overlay2/24a0976a392026ec49c4f2fd855ac9133f1956336f01236f1de2bcfe2cbf1d1d/diff', 'WorkDir': '/var/lib/docker/overlay2/24a0976a392026ec49c4f2fd855ac9133f1956336f01236f1de2bcfe2cbf1d1d/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:4b7c01ed0534d4f9be9cf97d068da1598c6c20b26cb6134fad066defdb6d541d']

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.