copy_from

docker.image.copy_from(image, path_in_image, destination)

copy_to

docker.image.copy_to(base_image, local_path, path_in_image, new_tag=None)

exists

docker.image.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

docker.image.history()

Not yet implemented

import_

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

Import the contents from a tarball to create a filesystem image

Alias: docker.import_(...)

Arguments

  • changes List[str]: Apply Dockerfile instruction to the created image
  • message Optional[str]: Set commit message for imported image
  • platform Optional[str]: Set platform if server is multi-platform capable

inspect

docker.image.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

docker.image.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.

Arguments

  • context_path Union[str, pathlib.Path]: The path of the build context. Defaults to the current working directory
  • 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
  • file Optional[Union[str, pathlib.Path]]: The path of the Dockerfile, defaults to context_path/Dockerfile
  • 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
  • pull bool: Always attempt to pull a newer version of the image
  • tags Union[str, List[str]]: Tag or tags to put on the resulting image.
  • target Optional[str]: Set the target build stage to build.

Returns

A python_on_whales.Image

list

docker.image.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

docker.image.load(input, quiet=False)

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

Alias: docker.load(...)

Arguments

  • input Union[str, pathlib.Path, bytes, Iterator[bytes]]: Path or input stream to load the images from.
  • quiet bool: If you don't want to display the progress bars.

Returns

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

prune

docker.image.prune(all=False, filter={})

Remove unused images

Arguments

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

Returns:

The output of the CLI (the layers removed).

pull

docker.image.pull(x, quiet=False)

Pull one or more docker image(s)

Alias: docker.pull(...)

Arguments

  • 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.
  • quiet bool: If you don't want to see the progress bars.

Returns:

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

push

docker.image.push(x, quiet=False)

Push a tag or a repository to a registry

Alias: docker.push(...)

Arguments

  • 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.
  • quiet bool: If you don't want to see the progress bars.

Raises

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

remove

docker.image.remove(x, force=False, prune=True)

Remove one or more docker images.

Arguments

  • x Union[str, python_on_whales.Image, List[Union[str, python_on_whales.Image]]]: Single image or list of Docker images to remove. You can use tags or python_on_whales.Image objects.
  • force bool: Force removal of the image
  • prune bool: Delete untagged parents

Raises

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

save

docker.image.save(images, output=None)

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

Alias: docker.save(...)

Arguments

  • images Union[str, python_on_whales.Image, List[Union[str, python_on_whales.Image]]]: Single docker image or list of docker images to save
  • output Optional[Union[str, pathlib.Path]]: 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.

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

docker.image.tag(source_image, new_tag)

Adds a tag to a Docker image.

Alias: docker.tag(...)

Arguments

  • source_image Union[python_on_whales.Image, str]: The Docker image to tag. You can use a tag to reference it.
  • new_tag str: The tag to add to the Docker image.

Raises

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