Explain the SIZE column in "docker ps -s" and what "virtual" keyword means

[Niceplace]

File: engine/reference/commandline/ps.md

Under the SIZE column of the outpout of "docker ps -s". Is it possible to explain what the "virtual" keyword means ?

Example : for a container I am runing I can see 2.045 MB (virtual 540.5 MB) Does this mean that the container takes 2.045 MB on disk, or 540.5 MB ?

[mdlinville]

We may be able to explain it. This is not a Docker-specific concept. For now, there is a great explanation here: http://serverfault.com/questions/48582/how-is-memory-usage-reported-in-linux

[itsafire]

I'm confused. I understand the concept of virtual memory but @mstanleyjones are you sure the -s switch is about virtual memory ? Why is it reporting reporting a virtual size for stopped containers then ?

I understand the -s switch is about file sizes, right ?

[mdlinville]

@thaJeztah can you help here? I may be missing something.

[itsafire]

As I see it, the -s options outputs the size of additonal layers on top of the given image the container runs. The virtual size of all image layers plus the first value. Volumes are not counted. I see this behaviour with aufs on linux and on docker on mac. Right ?

[thaJeztah]

The "size" and "virtual size" describe the amount of disk space used by a container. Let me try and explain:

When starting a container, the image that the container is started from is mounted read-only. On top of that, a writable layer is mounted, in which any changes made to the container are written.

The read-only layers of an image can be shared between any container that is started from the same image, whereas the "writable" layer is unique per container (because: you don't want changes made in container "a" to appear in container "b" :smile:)

Back to the docker ps -s output;

• The "size" information shows the amount of data (on disk) that is used for the writable layer of each container
• The "virtual size" is the total amount of disk-space used for the read-only image data used by the container and the writable layer.

The reason it's named "virtual size", is that (as described earlier), the disk space for the read-only layer(s) can be shared between containers, so only take up disk space once (perhaps a different name ("shared" size?) would have been better in hindsight, but naming is hard :smile:). edit: virtual actually shows the combined size of the readonly layer (the image), and the writable layer of the container.

In the example below, I started 10 nginx containers;

CONTAINER ID        IMAGE                      COMMAND                  CREATED              STATUS              PORTS               NAMES                                         SIZE
6ca0cef8db8d        nginx                      "nginx -g 'daemon ..."   55 seconds ago       Up 54 seconds       80/tcp, 443/tcp     pedantic_mahavira                             2B (virtual 183MB)
0b75532c34d2        nginx                      "nginx -g 'daemon ..."   56 seconds ago       Up 55 seconds       80/tcp, 443/tcp     hardcore_haibt                                2B (virtual 183MB)
a86d8818795d        nginx                      "nginx -g 'daemon ..."   56 seconds ago       Up 55 seconds       80/tcp, 443/tcp     happy_pasteur                                 2B (virtual 183MB)
3e9151f0332d        nginx                      "nginx -g 'daemon ..."   57 seconds ago       Up 56 seconds       80/tcp, 443/tcp     pensive_khorana                               2B (virtual 183MB)
429c418114a1        nginx                      "nginx -g 'daemon ..."   57 seconds ago       Up 56 seconds       80/tcp, 443/tcp     nostalgic_bose                                2B (virtual 183MB)
01f6a0818b32        nginx                      "nginx -g 'daemon ..."   58 seconds ago       Up 57 seconds       80/tcp, 443/tcp     zen_davinci                                   2B (virtual 183MB)
9ed93ee43912        nginx                      "nginx -g 'daemon ..."   58 seconds ago       Up 58 seconds       80/tcp, 443/tcp     unruffled_ptolemy                             2B (virtual 183MB)
c7c17bf50744        nginx                      "nginx -g 'daemon ..."   59 seconds ago       Up 58 seconds       80/tcp, 443/tcp     zen_khorana                                   2B (virtual 183MB)
a7b0502d95ce        nginx                      "nginx -g 'daemon ..."   About a minute ago   Up About a minute   80/tcp, 443/tcp     gallant_leavitt                               2B (virtual 183MB)
8b9e9ee6c4e8        nginx                      "nginx -g 'daemon ..."   About a minute ago   Up About a minute   80/tcp, 443/tcp     clever_pasteur                                2B (virtual 183MB)

All these containers use the same image, so the "Virtual size" (183MB in the example) is used only once, irregardless of how many containers are started from the same image - I can start 1 container or a thousand; no extra disk space is used. The "Size" (2B in the example) is unique per container though, so the total space used on disk is:

183MB + 10 * 2B

Be aware that the size shown does not include all disk space used for a container. Things that are not included currently are;

• disk space used for log-files (if you use the json-file logging driver) - which can be quite a bit if your container generates a lot of logs, and log-rotation (max-file / max-size logging options) is not configured
• volumes used by the container
• disk space used for the container's configuration files (hostconfig.json, config.v2.json, hosts, hostname, resolv.conf) - although these files are small
• memory written to disk (if swapping is enabled)
• checkpoints (if you're using the experimental checkpoint/restore feature)

[aryamsft]

Is there anyway to determine the total amount of disk space used by each container including log files, volumes, container config files, memory written to disk and checkpoints?

Can this be done via using docker restful API's? See link here: https://docs.docker.com/engine/api/v1.37/#operation/ContainerStats

[yonglam]

@thaJeztah I have two containers created from the same image, but why their virtual size is different? One is 'size 185.9 GB (virtual 196.7 GB)', the other is 'size 74.83 GB (virtual 85.6 GB)'.

[thaJeztah]

@yonglam "same image", but also same version of the image? Were they started at different points in time? For example;

(using docker image tag just for illustration);

myimage:latest is created, and a container is started with it;

docker image tag busybox myimage:latest 
docker run -dit --name container1 myimag

docker ps -s

CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS              PORTS               NAMES               SIZE
7767a6e5b649        myimage             "sh"                     About a minute ago   Up About a minute                       container1          0B (virtual 1.15MB)

myimage is updated with a new version, and a second container is started

docker image tag ubuntu myimage:latest
docker run -dit --name container2 myimage

docker ps -s 

CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS              PORTS               NAMES               SIZE
74f0e474467c        myimage             "/bin/bash"              About a minute ago   Up About a minute                       container2          0B (virtual 79.6MB)

Both were stared from "the same image"

CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS              PORTS               NAMES               SIZE
74f0e474467c        myimage             "/bin/bash"              About a minute ago   Up About a minute                       container2          0B (virtual 79.6MB)
7767a6e5b649        8c811b4aec35        "sh"                     About a minute ago   Up About a minute                       container1          0B (virtual 1.15MB)

[yonglam]

@thaJeztah Thank you for your response. I don't think they are different image versions. Because the image tagged latest was created at 2017-12-04. It is far before I pull the image. I created the first container about 3 months ago, and the second one about 13 days ago. What I did was:

docker pull docker.xx.com:8080/my-jenkins-node-full:latest
docker run -d --net=host --name the_first docker.xx.com:8080/my-jenkins-node-full:latest  
docker run -d --net=host --name the_second docker.xx.com:8080/my-jenkins-node-full:latest 

the docker version is 1.10.3 (linux/amd64)

[mdlinville]

If they are each Jenkins images, they are probably carrying different state in the container's writable layer, which is always unique per running container.

[thaJeztah]

That wouldn't explain the difference in virtual size (which should be the read-only layers); I do see @yonglam is using a very old version of Docker, which could be related (could be a presentation bug), or they were actually started from different images;

@yonglam what does docker inspect show for each of those containers? Mainly the .Image and .Config.Image properties;

docker inspect --format '{{.Image}} {{.Config.Image}}'  the_first the_second

Should show something like;

sha256:c51a2cac7341fe55d38feb70157eb12d56b2039977d4175229432de09bd18896 docker.xx.com:8080/my-jenkins-node-full:latest 
sha256:c51a2cac7341fe55d38feb70157eb12d56b2039977d4175229432de09bd18896 docker.xx.com:8080/my-jenkins-node-full:latest 

[yonglam]

They have the same image's sha. @thaJeztah

[root@Linux64 ~]# docker inspect --format '{{.Image}} {{.Config.Image}}' the_first the second
sha256:c9a1b52800257d545ad617981fd8ac204619859c824d05b1bb2604442a52cc43 docker.xx.com:8080/my-jenkins-node-full:latest
sha256:c9a1b52800257d545ad617981fd8ac204619859c824d05b1bb2604442a52cc43 docker.xx.com:8080/my-jenkins-node-full:latest

I will update my docker.

[thaJeztah]

Erm, actually, had my wires cross; @mistyhacks is absolutely right; Virtual Size shows both the read-only and writable layer 😊;

If they are each Jenkins images, they are probably carrying different state in the container's writable layer, which is always unique per running container.

So yes, if those containers are writing lots of files to the container's filesystem itself (not to a volume), then the Virtual Size would grow as well (as it's the sum of both the image's size, and all files written in the container's filesystem);

docker run -dit --name foobar alpine
docker run -dit --name foobar2 alpine

docker exec foobar sh -c ' dd if=/dev/zero of=output.dat  bs=24M  count=1'

docker ps -s
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES                                     SIZE
60bab76f2ae8        alpine              "/bin/sh"           33 seconds ago      Up 32 seconds                           foobar2                                   0B (virtual 4.15MB)
9a6e24f0cdfe        alpine              "/bin/sh"           36 seconds ago      Up 35 seconds                           foobar                                    25.2MB (virtual 29.3MB)

[forestjohnsonpeoplenet]

although I acknowledge that google does a good job of indexing this github issue, and most developers and infrastructure engineers will be able to find it if they need it, this information should still be easily locate-able in the docker documentation and this issue should not be closed until then.

[thaJeztah]

@forestjohnsonpeoplenet I see this ticket was closed by a pull request in the documentation repository: https://github.com/docker/docker.github.io/pull/3615

That PR added this section to the documentation; https://docs.docker.com/storage/storagedriver/#container-size-on-disk

If you think more information would be needed for the documentation; could you open a ticket in that issue tracker (with some description which information you were looking for, but could not find) so that it doesn't get lost?

You can open a new issue from that page in the documentation ("request docs changes" link on the right-hand side of that page), or using this link; https://github.com/docker/docker.github.io/issues/new

[forestjohnsonpeoplenet]

I guess I am talking about a web usability issue, not a "information is missing" issue.

I think it should be here, since thats where I looked. https://docs.docker.com/engine/reference/commandline/ps/

I would never have guessed to look inside a storage driver article for information on the docker ps command.

Thanks for the reply and information on how to create an issue !!! very helpful :)

Here is my PR: ~https://github.com/docker/docker.github.io/pull/8371~ https://github.com/docker/cli/pull/1697

Hope this helps.

[docker-robott]

Closed issues are locked after 30 days of inactivity. This helps our team focus on active issues.

If you have found a problem that seems similar to this, please open a new issue.

/lifecycle locked