Docker – The USER instruction

How to check for updates on Windows Server 2019

The USER instruction allows you to set the current user (and group) for all of the instructions that follow in the Dockerfile, and for the containers that are run from the built image. The syntax for the USER instruction is as follows:

# User instruction syntax
USER <user>[:<group>] or

If a named user (or group) is provided as parameters to the USER instruction, that user (and group) must already exist in the passwd file (or group file) of the system, or a build error will occur. If you provide the UID (or GID) as the parameter to the USER command, the check to see whether the user (or group) exists is not performed. Consider the following Dockerfile:

# USER instruction Dockerfile for Docker Quick Start 
FROM alpine
LABEL maintainer="Earl Waud <>"
RUN id
USER games:games
run id
CMD ["sh"]

When the image build starts, the current user is root or UID=0 GID=0. Then, the USER instruction is executed to set the current user and group to games:games. Since this is the last use of the USER instruction in the Dockerfile, all containers run using the built image will have the current user (and group) set to games. Here is what the build and run look like:

Notice that the output from Step 3/6:RUN id shows the current user as root, and then in Step 5/6 (which is after the USER instruction) it shows the current user as games. Finally, notice that the container run from the image has the current user games. The USER instruction creates a zero-byte-sized layer in the image.

Comments are closed.