Images

Manage images on the server.

Methods available on client.images:

class ImageCollection
build(**kwargs)

Build an image and return it. Similar to the docker build command. Either path or fileobj must be set.

If you already have a tar file for the Docker build context (including a Dockerfile), pass a readable file-like object to fileobj and also pass custom_context=True. If the stream is also compressed, set encoding to the correct value (e.g gzip).

If you want to get the raw output of the build, use the build() method in the low-level API.

Parameters:

  • path (str) – Path to the directory containing the Dockerfile

  • fileobj – A file object to use as the Dockerfile. (Or a file-like object)

  • tag (str) – A tag to add to the final image

  • quiet (bool) – Whether to return the status

  • nocache (bool) – Don’t use the cache when set to True

  • rm (bool) – Remove intermediate containers. The docker build command now defaults to --rm=true, but we have kept the old default of False to preserve backward compatibility

  • timeout (int) – HTTP timeout

  • custom_context (bool) – Optional if using fileobj

  • encoding (str) – The encoding for a stream. Set to gzip for compressing

  • pull (bool) – Downloads any updates to the FROM image in Dockerfiles

  • forcerm (bool) – Always remove intermediate containers, even after unsuccessful builds

  • dockerfile (str) – path within the build context to the Dockerfile

  • buildargs (dict) – A dictionary of build arguments

  • container_limits (dict) –

    A dictionary of limits applied to each container created by the build process. Valid keys:

    • memory (int): set memory limit for build

    • memswap (int): Total memory (memory + swap), -1 to disable

      swap

    • cpushares (int): CPU shares (relative weight)

    • cpusetcpus (str): CPUs in which to allow execution, e.g.,

      "0-3", "0,1"

  • shmsize (int) – Size of /dev/shm in bytes. The size must be greater than 0. If omitted the system uses 64MB

  • labels (dict) – A dictionary of labels to set on the image

  • cache_from (list) – A list of images used for build cache resolution

  • target (str) – Name of the build-stage to build in a multi-stage Dockerfile

  • network_mode (str) – networking mode for the run commands during build

  • squash (bool) – Squash the resulting images layers into a single layer.

  • extra_hosts (dict) – Extra hosts to add to /etc/hosts in building containers, as a mapping of hostname to IP address.

  • platform (str) – Platform in the format os[/arch[/variant]].

  • isolation (str) – Isolation technology used during build. Default: None.

  • use_config_proxy (bool) – If True, and if the docker client configuration file (~/.docker/config.json by default) contains a proxy configuration, the corresponding environment variables will be set in the container being built.

Returns:

The first item is the Image object for the

image that was built. The second item is a generator of the build logs as JSON-decoded objects.

Return type:

(tuple)

Raises:

  • docker.errors.BuildError – If there is an error during the build.

  • docker.errors.APIError – If the server returns any other error.

  • TypeError – If neither path nor fileobj is specified.

get(name)

Gets an image.

Parameters:

name (str) – The name of the image.

Returns:

The image.

Return type:

(Image)

Raises:

  • docker.errors.ImageNotFound – If the image does not exist.

  • docker.errors.APIError – If the server returns an error.

get_registry_data(name, auth_config=None)

Gets the registry data for an image.

Parameters:

  • name (str) – The name of the image.

  • auth_config (dict) – Override the credentials that are found in the config for this request. auth_config should contain the username and password keys to be valid.

Returns:

The data object.

Return type:

(RegistryData)

Raises:

docker.errors.APIError – If the server returns an error.

list(**kwargs)

List images on the server.

Parameters:

  • name (str) – Only show images belonging to the repository name

  • all (bool) – Show intermediate image layers. By default, these are filtered out.

  • filters (dict) –

    Filters to be processed on the image list. Available filters: - dangling (bool) - label (str|list): format either "key", "key=value"

    or a list of such.

Returns:

The images.

Return type:

(list of Image)

Raises:

docker.errors.APIError – If the server returns an error.

load(data)

Load an image that was previously saved using save() (or docker save). Similar to docker load.

Parameters:

data (binary) – Image data to be loaded.

Returns:

The images.

Return type:

(list of Image)

Raises:

docker.errors.APIError – If the server returns an error.

prune(filters=None)

Delete unused images

Parameters:

filters (dict) – Filters to process on the prune list. Available filters: - dangling (bool): When set to true (or 1), prune only unused and untagged images.

Returns:

A dict containing a list of deleted image IDs and

the amount of disk space reclaimed in bytes.

Return type:

(dict)

Raises:

docker.errors.APIError – If the server returns an error.

pull(repository, tag=None, all_tags=False, **kwargs)

Pull an image of the given name and return it. Similar to the docker pull command. If tag is None or empty, it is set to latest. If all_tags is set, the tag parameter is ignored and all image tags will be pulled.

If you want to get the raw pull output, use the pull() method in the low-level API.

Parameters:

  • repository (str) – The repository to pull

  • tag (str) – The tag to pull

  • auth_config (dict) – Override the credentials that are found in the config for this request. auth_config should contain the username and password keys to be valid.

  • platform (str) – Platform in the format os[/arch[/variant]]

  • all_tags (bool) – Pull all image tags

Returns:

The image that has been pulled.

If all_tags is True, the method will return a list of Image objects belonging to this repository.

Return type:

(Image or list)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> # Pull the image tagged `latest` in the busybox repo
>>> image = client.images.pull('busybox')

>>> # Pull all tags in the busybox repo
>>> images = client.images.pull('busybox', all_tags=True)
push(repository, tag=None, **kwargs)

Push an image or a repository to the registry. Similar to the docker push command.

Parameters:

  • repository (str) – The repository to push to

  • tag (str) – An optional tag to push

  • stream (bool) – Stream the output as a blocking generator

  • auth_config (dict) – Override the credentials that are found in the config for this request. auth_config should contain the username and password keys to be valid.

  • decode (bool) – Decode the JSON data from the server into dicts. Only applies with stream=True

Returns:

The output from the server.

Return type:

(generator or str)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> resp = client.api.push(
...     'yourname/app',
...     stream=True,
...     decode=True,
... )
... for line in resp:
...   print(line)
{'status': 'Pushing repository yourname/app (1 tags)'}
{'status': 'Pushing','progressDetail': {}, 'id': '511136ea3c5a'}
{'status': 'Image already pushed, skipping', 'progressDetail':{},
 'id': '511136ea3c5a'}
...
remove(*args, **kwargs)

Remove an image. Similar to the docker rmi command.

Parameters:

  • image (str) – The image to remove

  • force (bool) – Force removal of the image

  • noprune (bool) – Do not delete untagged parents

search(*args, **kwargs)

Search for images on Docker Hub. Similar to the docker search command.

Parameters:

  • term (str) – A term to search for.

  • limit (int) – The maximum number of results to return.

Returns:

The response of the search.

Return type:

(list of dicts)

Raises:

docker.errors.APIError – If the server returns an error.

Image objects

class Image

An image on the server.

attrs

The raw representation of this object from the server.

id

The ID of the object.

labels

The labels of an image as dictionary.

short_id

The ID of the image truncated to 12 characters, plus the sha256: prefix.

tags

The image’s tags.

history()

Show the history of an image.

Returns:

The history of the image.

Return type:

(list)

Raises:

docker.errors.APIError – If the server returns an error.

reload()

Load this object from the server again and update attrs with the new data.

save(chunk_size=2097152, named=False)

Get a tarball of an image. Similar to the docker save command.

Parameters:

  • chunk_size (int) – The generator will return up to that much data per iteration, but may return less. If None, data will be streamed as it is received. Default: 2 MB

  • named (str or bool) – If False (default), the tarball will not retain repository and tag information for this image. If set to True, the first tag in the tags list will be used to identify the image. Alternatively, any element of the tags list can be used as an argument to use that specific tag as the saved identifier.

Returns:

A stream of raw archive data.

Return type:

(generator)

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> image = cli.images.get("busybox:latest")
>>> f = open('/tmp/busybox-latest.tar', 'wb')
>>> for chunk in image.save():
>>>   f.write(chunk)
>>> f.close()
tag(repository, tag=None, **kwargs)

Tag this image into a repository. Similar to the docker tag command.

Parameters:

  • repository (str) – The repository to set for the tag

  • tag (str) – The tag name

  • force (bool) – Force

Raises:

docker.errors.APIError – If the server returns an error.

Returns:

True if successful

Return type:

(bool)

RegistryData objects

class RegistryData

Image metadata stored on the registry, including available platforms.

attrs

The raw representation of this object from the server.

id

The ID of the object.

short_id

The ID of the image truncated to 12 characters, plus the sha256: prefix.

has_platform(platform)

Check whether the given platform identifier is available for this digest.

Parameters:

platform (str or dict) – A string using the os[/arch[/variant]] format, or a platform dictionary.

Returns:

True if the platform is recognized as available, False otherwise.

Return type:

(bool)

Raises:

docker.errors.InvalidArgument – If the platform argument is not a valid descriptor.

pull(platform=None)

Pull the image digest.

Parameters:

  • platform (str) – The platform to pull the image for.

  • Default – None

Returns:

A reference to the pulled image.

Return type:

(Image)

reload()

Load this object from the server again and update attrs with the new data.