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:b1d9df8ab81559494794e522b380878cf9ba82d4c1fb67293bcf931c3aa69ae4
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:80dd3c3b9c6cecb9f1667e9290b3bc61b78c2678c02cbdae5f0fea92cc6734ab']
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-11-19 17:29:25.973758+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:3ba7f9a61d88dd09bb6ac9166cec39891772edc997c4c1da55e50a27f2647e48' 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 = 78117252
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/72efcd8391714be72ebc986a431f225af551cdd524b173746fe069c7256d7fcd/merged', 'UpperDir': '/var/lib/docker/overlay2/72efcd8391714be72ebc986a431f225af551cdd524b173746fe069c7256d7fcd/diff', 'WorkDir': '/var/lib/docker/overlay2/72efcd8391714be72ebc986a431f225af551cdd524b173746fe069c7256d7fcd/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:687d50f2f6a697da02e05f2b2b9cb05c1d551f37c404ebe55fdec44b0ae8aa5c']
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.