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

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:278628f08d4979fb9af9ead44277dbc9c92c2465922310916ad0c46ec9999295']

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-10-16 09:25:57.559746+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:3cfd7549922ae8741a1825df62a5d01a4d4439c4c1e5c590074b9da9386b4143' 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 = 78114607

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/0497d60bf97206599c195c2bbb64e444f9f6ff7e3c51affe8b6debad58ed868d/merged', 'UpperDir': '/var/lib/docker/overlay2/0497d60bf97206599c195c2bbb64e444f9f6ff7e3c51affe8b6debad58ed868d/diff', 'WorkDir': '/var/lib/docker/overlay2/0497d60bf97206599c195c2bbb64e444f9f6ff7e3c51affe8b6debad58ed868d/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:27123a71e85e0540333291adccf7b9c340d089e8c3717c380d3b75cc8c7df90f']

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.