What is .build-deps for apk add --virtual command?

Question

What is .build-deps in the following command? I can't find an explanation in the Alpine docs. Is this a file that is predefined? Is see this referenced in many Dockerfiles.

RUN apk add --no-cache --virtual .build-deps \
gcc \
freetype-dev \
musl-dev

RUN pip install --no-cache-dir <packages_that_require_gcc...> \

RUN apk del .build-deps

Note, having the del in a separate RUN command will not reduce the image size, as the delete is run in a new layer in the filesystem. — scipilot, Apr 08 '18 at 06:25
why? docker image is an UFS, apk del in a new layer can also reduce the image size. — focus zheng, Feb 07 '23 at 03:04

score 354 · Accepted Answer · edited Jan 31 '22 at 08:35

If you see the documentation

-t, --virtual NAME    Instead of adding all the packages to 'world', create a new 
                      virtual package with the listed dependencies and add that 
                      to 'world'; the actions of the command are easily reverted 
                      by deleting the virtual package

What that means is when you install packages, those packages are not added to global packages. And this change can be easily reverted. So if I need gcc to compile a program, but once the program is compiled I no more need gcc.

I can install gcc, and other required packages in a virtual package and all of its dependencies and everything can be removed this virtual package name. Below is an example usage

RUN apk add --virtual mypacks gcc vim \
 && apk del mypacks

The next command will delete all 18 packages installed with the first command.

In docker these must be executed as a single RUN command (as shown above), otherwise it will not reduce the image size.

Also worth mentioning that it's important to use a unique name for a virtual package, not existing in currently configured repositories, otherwise installing packages succeeds but doesn't install what you need. — bazeusz, Mar 17 '20 at 12:03
Note: you must execute it in one RUN command, else it cannot be deleted from the previous Docker image layer https://stackoverflow.com/a/49714913/1577357 — Zulhilmi Zainudin, Jul 07 '20 at 09:05

score 22 · Answer 2 · edited May 26 '21 at 21:51

.build-deps is an arbitrary name to call a "virtual package" in Alpine, where you will add packages.

It creates an extra 'world' of packages, that you will need for a limited period of time (e.g. compilers for building other things).

Its main purpose is to keep your image as lean and light as possible, because you can easily get rid of it once those packages were used.

Please remember that it should be included in the same RUN if you want to achieve the main purpose of lightweight.

What is .build-deps for apk add --virtual command?

2 Answers2

Linked