Images

class aiodocker.images.DockerImages(docker: Docker)

build(*, remote: str | None = None, fileobj: SupportsRead[bytes] | None = None, path_dockerfile: str | None = None, tag: str | None = None, quiet: bool = False, nocache: bool = False, buildargs: Mapping[str, str] | None = None, pull: bool = False, rm: bool = True, forcerm: bool = False, labels: Mapping[str, str] | None = None, platform: str | None = None, stream: Literal[False] = False, encoding: str | None = None, timeout: float | ClientTimeout | Sentinel | None = SENTINEL) → List[dict[str, Any]]

build(*, remote: str | None = None, fileobj: SupportsRead[bytes] | None = None, path_dockerfile: str | None = None, tag: str | None = None, quiet: bool = False, nocache: bool = False, buildargs: Mapping[str, str] | None = None, pull: bool = False, rm: bool = True, forcerm: bool = False, labels: Mapping[str, str] | None = None, platform: str | None = None, stream: Literal[True], encoding: str | None = None, timeout: float | ClientTimeout | Sentinel | None = SENTINEL) → AsyncIterator[dict[str, Any]]

Build an image given a remote Dockerfile or a file object with a Dockerfile inside

Parameters:

• path_dockerfile – path within the build context to the Dockerfile

• remote – a Git repository URI or HTTP/HTTPS context URI

• tag – a name and optional tag to apply to the image

• quiet – suppress verbose build output

• nocache – do not use the cache when building the image

• rm – remove intermediate containers after a successful build

• pull – downloads any updates to the FROM image in Dockerfiles

• encoding – set Content-Encoding for the file object your send

• forcerm – always remove intermediate containers, even upon failure

• labels – arbitrary key/value labels to set on the image

• platform – platform in the format os[/arch[/variant]]

• fileobj – a tar archive compressed or not

• timeout – timeout for the build operation (infinite by default)

Raises:

DockerStreamError – If the Docker Engine reports an error in the build progress stream (e.g. a failing build step). Subclass of DockerError.

async delete(name: str, *, force: bool = False, noprune: bool = False) → List[Any]

Remove an image along with any untagged parent images that were referenced by that image

Parameters:

• name – name/id of the image to delete

• force – remove the image even if it is being used by stopped containers or has other tags

• noprune – don’t delete untagged parent images

Returns:

List of deleted images

export_image(name: str, timeout: float | ClientTimeout | Sentinel | None = Sentinel.TOKEN)

Get a tarball of an image by name or id.

Parameters:

• name – name/id of the image to be exported

• timeout – timeout for the export operation (infinite by default)

Returns:

Streamreader of tarball image

async get(name: str) → dict[str, Any]

async history(name: str) → dict[str, Any]

import_image(data, stream: bool = False, timeout: float | ClientTimeout | Sentinel | None = Sentinel.TOKEN)

Import tarball of image to docker.

Parameters:

• data – tarball data of image to be imported

• stream – stream the response

• timeout – timeout for the import operation (infinite by default)

Returns:

Tarball of the image

Raises:

DockerStreamError – If the Docker Engine reports an error in the import progress stream. Subclass of DockerError.

async inspect(name: str) → dict[str, Any]

Return low-level information about an image

Parameters:

name – name of the image

async list(*, filters: Mapping[str, Any] | str | None = None, **params) → List[Any]

List of images

Parameters:

• filters – Filter expressions for the listing. Accepts a mapping like {"dangling": ["true"]}, {"label": ["foo=bar"]}, or {"reference": ["busybox"]}. A pre-encoded JSON string is also accepted for backwards compatibility, but is deprecated and will be removed in 1.0.

• **params – Additional query parameters forwarded to GET /images/json (e.g. all, digests, shared_size).

async prune(*, filters: Mapping[str, Any] | None = None) → dict[str, Any]

Delete unused images

Parameters:

filters –

Filter expressions to limit which images are pruned. Available filters: - dangling: When set to “true” (or “1”), prune only unused images that are not tagged.

When set to “false” (or “0”), prune all unused images.

• until: Only remove images created before given timestamp

• label: Only remove images with (or without, if label!=<key> is used) the specified labels

Returns:

Dictionary containing information about deleted images and space reclaimed

async prune_builds(*, reserved_space: int | None = None, max_used_space: int | None = None, min_free_space: int | None = None, all_builds: bool | None = None, filters: Mapping[str, Any] | None = None) → dict[str, Any]

Delete builder cache

Parameters:

• reserved_space – Amount of disk space in bytes to keep for cache.

• max_used_space – Maximum amount of disk space allowed to keep for cache.

• min_free_space – Target amount of free disk space after pruning.

• all_builds – When true, consider all unused build cache objects for pruning. When false, only consider dangling build cache objects for pruning.

• filters – Filter expressions to limit what types of build cache objects are pruned. Available filters: - until: Only remove build cache objects created before given timestamp. - id: id=<id> - parent: parent=<id> - type: type=<string> - description: description=<string> - inuse - shared - private

Returns:

Dictionary containing information about deleted caches and space reclaimed

pull(from_image: str, *, auth: JSONObject | str | bytes | None = None, tag: str | None = None, repo: str | None = None, platform: str | None = None, stream: Literal[False] = False, timeout: float | Sentinel | None = SENTINEL) → List[dict[str, Any]]

pull(from_image: str, *, auth: JSONObject | str | bytes | None = None, tag: str | None = None, repo: str | None = None, platform: str | None = None, stream: Literal[True], timeout: float | Sentinel | None = SENTINEL) → AsyncIterator[dict[str, Any]]

Similar to docker pull, pull an image locally

Parameters:

• fromImage – name of the image to pull, optionally including a tag (name:tag) or digest (name@sha256:...)

• repo – repository name given to an image when it is imported

• tag – tag to pull. When omitted and from_image does not embed a tag (name:tag) or digest (name@sha256:...), defaults to "latest" to match the behavior of the docker pull CLI. Pass an empty string explicitly to request the Docker Engine’s “pull all tags” behavior. To pull by digest, embed it in from_image.

• platform – platform in the format os[/arch[/variant]]

• auth – special {‘auth’: base64} pull private repo

Raises:

DockerStreamError – If the Docker Engine reports an error in the progress stream (e.g. the registry rejected the pull with 403 Forbidden). Subclass of DockerError.

push(name: str, *, auth: JSONObject | str | bytes | None = None, tag: str | None = None, stream: Literal[False] = False, timeout: float | Sentinel | None = SENTINEL) → List[dict[str, Any]]

push(name: str, *, auth: JSONObject | str | bytes | None = None, tag: str | None = None, stream: Literal[True], timeout: float | Sentinel | None = SENTINEL) → AsyncIterator[dict[str, Any]]

Similar to docker push, push an image to a registry.

Raises:

DockerStreamError – If the Docker Engine reports an error in the progress stream (e.g. the registry rejected the push with 403 Forbidden). Subclass of DockerError.

async tag(name: str, repo: str, *, tag: str | None = None) → bool

Tag the given image so that it becomes part of a repository.

Parameters:

• name – name/id of the image to be tagged

• repo – the repository to tag in

• tag – the name for the new tag