How to get total size of a docker image by docker API properly?

Question

I want to get total size of a docker image by docker API, such as GET /v2/<name>/manifests/<reference> which is described here docker spec

I got a list of layers with size, such as this example, I add up these sizes but got a number which is smaller than docker images command show, as i know the docker registry stores these layers files as gzipped tar files, so this sum should be smaller than the size which is showed by docker images command.

How to get the total image size properly by docker API? I want to get the same size as docker images command show.

Answer 1

TLDR

The size given by docker images is the uncompressed size of the image installed locally, you can only get from the registry the size of the compressed images (for each architecture and if you want for each layer).

From a local image

The size given by docker images is the uncompressed size of an image on your system.

# getting the size of alpine:latest
docker images alpine:latest --format "{{.Repository}}:{{.Tag}} -> {{.Size}}"

# alpine:latest -> 5.57MB

You can get the same information if you download the image locally by using the docker inspect command.

docker inspect alpine:latest | jq '.[].Size' 

# 5573013

From a registry

As far as I know you can only get from a registry the compressed size of an image.

curl -s https://hub.docker.com/v2/repositories/library/alpine/tags/ | \
        jq '.results[] | select(.name=="latest") | .full_size'

# 2796860

In fact the registry can give the size of the image for each architecture.

curl -s https://hub.docker.com/v2/repositories/library/alpine/tags/ | \
        jq '.results[] | select(.name=="latest") | .images[] | {architecture: .architecture, size: .size}'

# {
#   "architecture": "arm",
#   "size": 2405675
# }
# {
#   "architecture": "arm",
#   "size": 2601912
# }
# {
#   "architecture": "386",
#   "size": 2791407
# }
# {
#   "architecture": "s390x",
#   "size": 2565829
# }
# {
#   "architecture": "ppc64le",
#   "size": 2803218
# }
# {
#   "architecture": "amd64",
#   "size": 2796860
# }
# {
#   "architecture": "arm64",
#   "size": 2706555
# }

You can even get the detail of the compressed size of each layer by using the docker manifest inspect experimental command.

# activate experimental mode
export DOCKER_CLI_EXPERIMENTAL=enabled 

docker manifest inspect -v alpine:latest | \
       jq '.[] | select(.Descriptor.platform.architecture=="amd64") | .SchemaV2Manifest.layers[].size'

# 2796860

If there is multiple layers you can sum them. Here is an example with jupyter/base-notebook:latest

# getting the size through the API
curl -s https://hub.docker.com/v2/repositories/jupyter/base-notebook/tags | \ 
        jq '.results[] | select(.name=="latest") | .full_size'

# 187647701

# summing each layer
docker manifest inspect jupyter/base-notebook:latest | jq '[.layers[].size] | add' 

# 187647701