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: |
|
Returns: |
- The first item is the
Image object for the
image that was build. 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: |
|
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
>>> for line in client.api.push('yourname/app', stream=True, decode=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.
- 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 10 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: | (str) |
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 10 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.