ImageCLI

exists

exists(x)

Returns True if the image exists. False otherwise.

It's just calling docker.image.inspect(...) and verifies that it doesn't throw a python_on_whales.exceptions.NoSuchImage.

Returns

A `bool`

history

history()

Not yet implemented

import_

import_(source, tag=None, changes=[], message=None, platform=None)

Import the contents from a tarball to create a filesystem image

Alias: docker.import_(...)

Parameters:

Name	Type	Description	Default
`changes`	`List[str]`	Apply Dockerfile instruction to the created image	`[]`
`message`	`Optional[str]`	Set commit message for imported image	`None`
`platform`	`Optional[str]`	Set platform if server is multi-platform capable	`None`

inspect

inspect(x)

Creates a python_on_whales.Image object.

Returns

`python_on_whales.Image`, or `List[python_on_whales.Image]` if the input
was a list of strings.

Raises

`python_on_whales.exceptions.NoSuchImage` if one of the images does not exists.

legacy_build

legacy_build(context_path, add_hosts={}, build_args={}, cache=True, file=None, labels={}, network=None, pull=False, tags=[], target=None)

Build a Docker image with the old Docker builder (meaning not using buildx/buildkit)

As the name implies this is a legacy building method. Users are strongly encouraged to use docker.build() instead. The legacy builder will not be available in docker v22.06 and above.

This function also won't run the legacy builder if the environment variable DOCKER_BUILDKIT is set to 1 or if you had run previously docker buildx install from bash or docker.buildx.install() from Python.

Some resources on why moving to buildx/buildkit is necessary:

A python_on_whales.Image is returned, even when using multiple tags. That is because it will produce a single image with multiple tags.

Parameters:

Name	Type	Description	Default
`context_path`	`ValidPath`	The path of the build context. Defaults to the current working directory	required
`add_hosts`	`Dict[str, str]`	Hosts to add. `add_hosts={"my_host1": "192.168.32.35"}`	`{}`
`build_args`	`Dict[str, str]`	The build arguments. ex `build_args={"PY_VERSION": "3.7.8", "UBUNTU_VERSION": "20.04"}`.	`{}`
`cache`	`bool`	Whether or not to use the cache, defaults to True	`True`
`file`	`Optional[ValidPath]`	The path of the Dockerfile, defaults to `context_path/Dockerfile`	`None`
`labels`	`Dict[str, str]`	Dict of labels to add to the image. `labels={"very-secure": "1", "needs-gpu": "0"}` for example.	`{}`
`network`	`Optional[str]`	which network to use when building the Docker image	`None`
`pull`	`bool`	Always attempt to pull a newer version of the image	`False`
`tags`	`Union[str, List[str]]`	Tag or tags to put on the resulting image.	`[]`
`target`	`Optional[str]`	Set the target build stage to build.	`None`

Returns

A `python_on_whales.Image`

list

list(repository_or_tag=None, filters={}, all=False)

Returns the list of Docker images present on the machine.

Alias: docker.images()

Note that each image may have multiple tags.

Returns

A `List[python_on_whales.Image]` object.

load

load(input, quiet=False)

Loads one or multiple Docker image(s) from a tar or an iterator of bytes.

Alias: docker.load(...)

Parameters:

Name	Type	Description	Default
`input`	`Union[ValidPath, bytes, Iterator[bytes]]`	Path or input stream to load the images from.	required
`quiet`	`bool`	If you don't want to display the progress bars.	`False`

Returns

`None` when using bytes as input. A `List[str]` (list of tags)
 when a path is provided.

prune

prune(all=False, filter={})

Remove unused images

Parameters:

Name	Type	Description	Default
`all`	`bool`	Remove all unused images, not just dangling ones	`False`
`filter`	`Dict[str, str]`	Provide filter values (e.g. `{"until": "<timestamp>"}`)	`{}`

Returns:

Type	Description
`str`	The output of the CLI (the layers removed).

pull

pull(x, quiet=False, platform=None)

Pull one or more docker image(s)

Alias: docker.pull(...)

Parameters:

Name	Type	Description	Default
`x`	`Union[str, List[str]]`	The image name(s) . Can be a string or a list of strings. In case of list, multithreading is used to pull the images. The progress bars might look strange as multiple processes are drawing on the terminal at the same time.	required
`quiet`	`bool`	If you don't want to see the progress bars.	`False`
`platform`	`Optional[str]`	If you want to enforce a platform.	`None`

Returns:

Type	Description
`Union[Image, List[Image]]`	The Docker image loaded (`python_on_whales.Image` object).
`Union[Image, List[Image]]`	If a list was passed as input, then a `List[python_on_whales.Image]` will
`Union[Image, List[Image]]`	be returned.

push

push(x, quiet=False)

Push a tag or a repository to a registry

Alias: docker.push(...)

Parameters:

Name	Type	Description	Default
`x`	`Union[str, List[str]]`	Tag(s) or repo(s) to push. Can be a string or a list of strings. If it's a list of string, python-on-whales will push all the images with multiple threads. The progress bars might look strange as multiple processes are drawing on the terminal at the same time.	required
`quiet`	`bool`	If you don't want to see the progress bars.	`False`

Raises

`python_on_whales.exceptions.NoSuchImage` if one of the images does not exists.

remove

remove(x, force=False, prune=True)

Remove one or more docker images.

Parameters:

Name	Type	Description	Default
`x`	`Union[ValidImage, List[ValidImage]]`	Single image or list of Docker images to remove. You can use tags or `python_on_whales.Image` objects.	required
`force`	`bool`	Force removal of the image	`False`
`prune`	`bool`	Delete untagged parents	`True`

Raises

`python_on_whales.exceptions.NoSuchImage` if one of the images does not exists.

save

save(images, output=None)

Save one or more images to a tar archive. Returns a stream if output is None

Alias: docker.save(...)

Parameters:

Name	Type	Description	Default
`images`	`Union[ValidImage, List[ValidImage]]`	Single docker image or list of docker images to save	required
`output`	`Optional[ValidPath]`	Path of the tar archive to produce. If `output` is None, a generator of bytes is produced. It can be used to stream those bytes elsewhere, to another Docker daemon for example.	`None`

Returns

`Optional[Iterator[bytes]]`. If output is a path, nothing is returned.

Raises

`python_on_whales.exceptions.NoSuchImage` if one of the images does not exists.

Example

An example of transfer of an image from a local Docker daemon to a remote Docker daemon. We assume that the remote machine has an ssh access:

from python_on_whales import DockerClient

local_docker = DockerClient()
remote_docker = DockerClient(host="ssh://my_user@186.167.32.84")

image_name = "busybox:1"
local_docker.pull(image_name)
bytes_iterator = local_docker.image.save(image_name)

remote_docker.image.load(bytes_iterator)

Of course the best solution is to use a registry to transfer image but it's a cool example nonetheless.

tag

tag(source_image, new_tag)

Adds a tag to a Docker image.

Alias: docker.tag(...)

Parameters:

Name	Type	Description	Default
`source_image`	`Union[Image, str]`	The Docker image to tag. You can use a tag to reference it.	required
`new_tag`	`str`	The tag to add to the Docker image.	required

Raises

`python_on_whales.exceptions.NoSuchImage` if the image does not exists.