4.2.11.1 USER Non Root Runtime
A focused guide to USER Non Root Runtime, connecting core concepts with practical Docker and container operations.
USER non-root runtime is the practice of explicitly configuring a container's main process to run as an unprivileged user rather than root, significantly limiting what a compromised application process could do even if it were successfully exploited.
Creating a Dedicated Non-Root User
A common pattern creates a dedicated user specifically for running the application, rather than relying on whatever non-root users a base image might already include.
FROM python:3.12-slim
RUN useradd --create-home --shell /bin/bash appuser
WORKDIR /app
COPY --chown=appuser:appuser . .
USER appuser
CMD ["python", "app.py"]
Why Many Official Images Already Provide a Non-Root User
Several official runtime images include a pre-created, conventionally named non-root user specifically to make this pattern easier to adopt without needing to create one manually.
FROM node:20-alpine
USER node
The node image conventionally provides a user also named node, making this a one-line addition rather than requiring explicit user creation.
Verifying the Container Actually Runs as Non-Root
After configuring USER, confirming the container's main process actually runs as the intended unprivileged user is a useful verification step.
docker run --rm myapp whoami
docker run --rm myapp id
Handling File Permission Issues
Running as a non-root user can sometimes surface permission errors if files or directories the application needs to write to are not owned by, or writable by, that user — using --chown on relevant COPY instructions, or explicitly adjusting permissions, addresses this.
COPY --chown=appuser:appuser . /app
RUN mkdir -p /app/logs && chown appuser:appuser /app/logs
Why Non-Root Runtime Matters
Running as a non-root user is one of the most effective, low-cost security improvements available for a containerized application — it does not prevent every possible attack, but it meaningfully reduces what a successful one could actually accomplish, which is a significant improvement over the unrestricted default of running as root.