docker image

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_(...)

PARAMETER	DESCRIPTION
`changes`	Apply Dockerfile instruction to the created image TYPE: `Iterable[str]` DEFAULT: `()`
`message`	Set commit message for imported image TYPE: `Optional[str]` DEFAULT: `None`
`platform`	Set platform if server is multi-platform capable TYPE: `Optional[str]` DEFAULT: `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.

PARAMETER	DESCRIPTION
`context_path`	The path of the build context. Defaults to the current working directory TYPE: `ValidPath`
`add_hosts`	Hosts to add. `add_hosts={"my_host1": "192.168.32.35"}` TYPE: `Mapping[str, str]` DEFAULT: `{}`
`build_args`	The build arguments. ex `build_args={"PY_VERSION": "3.7.8", "UBUNTU_VERSION": "20.04"}`. TYPE: `Mapping[str, str]` DEFAULT: `{}`
`cache`	Whether or not to use the cache, defaults to True TYPE: `bool` DEFAULT: `True`
`file`	The path of the Dockerfile, defaults to `context_path/Dockerfile` TYPE: `Optional[ValidPath]` DEFAULT: `None`
`labels`	Mapping of labels to add to the image. `labels={"very-secure": "1", "needs-gpu": "0"}` for example. TYPE: `Mapping[str, str]` DEFAULT: `{}`
`network`	which network to use when building the Docker image TYPE: `Optional[str]` DEFAULT: `None`
`pull`	Always attempt to pull a newer version of the image TYPE: `bool` DEFAULT: `False`
`tags`	Tag or tags to put on the resulting image. TYPE: `Union[str, Iterable[str]]` DEFAULT: `()`
`target`	Set the target build stage to build. TYPE: `Optional[str]` DEFAULT: `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(...)

PARAMETER	DESCRIPTION
`input`	Path or input stream to load the images from. TYPE: `Union[ValidPath, bytes, Iterator[bytes]]`
`quiet`	If you don't want to display the progress bars. TYPE: `bool` DEFAULT: `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

PARAMETER	DESCRIPTION
`all`	Remove all unused images, not just dangling ones TYPE: `bool` DEFAULT: `False`
`filter`	Provide filter values (e.g. `{"until": "<timestamp>"}`) TYPE: `Mapping[str, str]` DEFAULT: `{}`

RETURNS	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(...)

PARAMETER	DESCRIPTION
`x`	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. TYPE: `Union[str, Iterable[str]]`
`quiet`	If you don't want to see the progress bars. TYPE: `bool` DEFAULT: `False`
`platform`	If you want to enforce a platform. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	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(...)

PARAMETER	DESCRIPTION
`x`	Tag(s) or repo(s) to push. Can be a string or an iterable of strings. If it's an iterable, 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. TYPE: `Union[str, Iterable[str]]`
`quiet`	If you don't want to see the progress bars. TYPE: `bool` DEFAULT: `False`

Raises

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

remove

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

Remove one or more docker images.

PARAMETER	DESCRIPTION
`x`	Single image or iterable of Docker images to remove. You can use tags or `python_on_whales.Image` objects. TYPE: `Union[ValidImage, Iterable[ValidImage]]`
`force`	Force removal of the image(s). TYPE: `bool` DEFAULT: `False`
`prune`	Delete untagged parents. TYPE: `bool` DEFAULT: `True`

Raises

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

save

save(images, output=None)

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

Alias: docker.save(...)

PARAMETER	DESCRIPTION
`images`	Single image or non-empty iterable of images to save. TYPE: `Union[ValidImage, Iterable[ValidImage]]`
`output`	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. TYPE: `Optional[ValidPath]` DEFAULT: `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 exist.

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 images, but it's a cool example nonetheless.

tag

tag(source_image, new_tag)

Adds a tag to a Docker image.

Alias: docker.tag(...)

PARAMETER	DESCRIPTION
`source_image`	The Docker image to tag. You can use a tag to reference it. TYPE: `Union[Image, str]`
`new_tag`	The tag to add to the Docker image. TYPE: `str`

Raises

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