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:df5de72bdb3b711aba4eca685b1f42c722cc8a1837ed3fbd548a9282af2d836d
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:34fea4f31bf187bc915536831fd0afc9d214755bf700b5cdb1336c82516d154e']
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 = 2022-08-02 01:30:56.165288+00:00
In [10]: super_print(image.container)
type = <class 'str'>, value = a6c72c2afd5de1ef2532e543e5f3230e16b7f82d7e737eaba5cf7713a1c8e4ba
In [11]: super_print(image.container_config)
type = <class 'python_on_whales.components.container.models.ContainerConfig'>, value = hostname='a6c72c2afd5d' 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 ["bash"]'] healthcheck=None args_escaped=None image='sha256:ea09a86efaaf01779c996ab54ab1f96bb704ae00a4b57e48ddf8d1f1b74f76c9' volumes=None working_dir=PosixPath('.') entrypoint=None network_disabled=None mac_address=None on_build=None labels={} stop_signal=None stop_timeout=None shell=None
In [12]: super_print(image.docker_version)
type = <class 'str'>, value = 20.10.12
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=['bash'] healthcheck=None args_escaped=None image='sha256:ea09a86efaaf01779c996ab54ab1f96bb704ae00a4b57e48ddf8d1f1b74f76c9' volumes=None working_dir=PosixPath('.') entrypoint=None network_disabled=None mac_address=None on_build=None labels=None stop_signal=None stop_timeout=None shell=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 = 77829614
In [19]: super_print(image.virtual_size)
type = <class 'int'>, value = 77829614
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/6c0136e325c7c55d10dd8e64c0c0f667948df2ae75078e0a16fd171fb562a533/merged', 'UpperDir': '/var/lib/docker/overlay2/6c0136e325c7c55d10dd8e64c0c0f667948df2ae75078e0a16fd171fb562a533/diff', 'WorkDir': '/var/lib/docker/overlay2/6c0136e325c7c55d10dd8e64c0c0f667948df2ae75078e0a16fd171fb562a533/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:629d9dbab5edeac7fa51f205839d7f9bb629a5e83548da3a183fb66c22fe7af7']
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
copy_from
Image.copy_from(path_in_image, destination)
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
Image.copy_to(local_path, path_in_image, new_tag=None)
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
Image.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.
reload
Image.reload()
remove
Image.remove(force=False, prune=True)
Remove this Docker image.
See the docker.image.remove
command for
information about the arguments.
save
Image.save(output=None)
Saves this Docker image in a tar.
See the docker.image.save
command for
information about the arguments.
tag
Image.tag(new_tag)
Add a tag to a Docker image.
See the docker.image.tag
command for
information about the arguments.