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 have a tar file for the Docker build context (including a Dockerfile) already, pass a readable file-like object to fileobj and also pass custom_context=True. If the stream is compressed also, 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
Returns:

The built image.

Return type:

(Image)

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.
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): format either key or key=value
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:Progress output as JSON objects
Return type:(generator)
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(name, tag=None, **kwargs)

Pull an image of the given name and return it. Similar to the docker pull command.

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
  • insecure_registry (bool) – Use an insecure registry
  • auth_config (dict) – Override the credentials that login() has set for this request. auth_config should contain the username and password keys to be valid.
Returns:

The image that has been pulled.

Return type:

(Image)

Raises:

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

Example

>>> image = client.images.pull('busybox')
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
  • insecure_registry (bool) – Use http:// to connect to the registry
  • auth_config (dict) – Override the credentials that login() has set for this request. auth_config should contain the username and password keys to be valid.
Returns:

The output from the server.

Return type:

(generator or str)

Raises:

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

Example

>>> for line in cli.push('yourname/app', stream=True):
...   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.
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