4.2.11 USER

USER is the Dockerfile instruction that sets which user (and optionally group) a container's main process, and any subsequent build instructions, run as — a key lever for security, since running as root by default grants more privilege than most applications actually need.

Basic Usage

USER switches the active user for everything that follows it in the Dockerfile, as well as for the container's main process once it starts.

RUN useradd --create-home appuser
USER appuser

Both subsequent build instructions and the container's eventual startup process run as appuser, not as root.

Specifying a User by Name or Numeric ID

USER accepts either a username (which must already exist in the image) or a numeric user ID, which can be used even if no corresponding named user has been created.

USER 1000

USER appuser:appgroup

The second form specifies both a user and a group explicitly.

Why the Default (Root) Is Risky

Without an explicit USER instruction, a container's main process runs as root by default, which means any vulnerability allowing arbitrary code execution within the container grants that code root-level privileges within its own namespace — a significantly larger blast radius than a properly restricted, non-root process would have.

FROM python:3.12-slim
COPY . /app
CMD ["python", "/app/app.py"]

Without a USER instruction, this container's process runs as root, which is unnecessary for most typical applications.

Switching Back to Root Temporarily

Build steps that genuinely need root privileges — installing system packages — can run before USER switches to a non-root user for the remainder of the file, or USER root can switch back temporarily if needed partway through.

RUN apt-get update && apt-get install -y curl
USER appuser

Why USER Matters

Explicitly setting a non-root USER is one of the most impactful, broadly applicable security practices available in a Dockerfile, directly limiting the potential consequences of any vulnerability in the application running inside the container.