Add Users to a Docker Container: Non-Root User Guide

Docker containers run as root by default. Fine for a quick test, a liability in production. This guide shows you how to add users to a Docker container the right way: bake non-root users into your image, pin UID/GID, fix volume permissions, and verify before you deploy.

Three approaches, in order of preference:

1. Dockerfile: create users at build time (recommended for anything that needs to survive a restart)
2. Runtime overrides: docker run -u and docker exec -u (debugging and one-off tasks)
3. UID/GID mapping: match container and host users to fix bind-mount permission headaches

This guide covers Ubuntu 24.04 and Alpine 3.24, Docker Compose V2, and Docker Engine 29.x. If you need a Linux VPS to practice on, you can start with a Hetzner VPS or Hostinger VPS.

VPS prices jumped across the board in 2026 — if you’re rethinking a rented box, see what changed and when a mini PC wins.

Why Run Containers as a Non-Root User?

Running as root in containers creates three problems:

• Security: If the application gets compromised, the attacker has root inside the container. On misconfigured hosts (especially with --privileged or writable bind mounts), that can escalate to root on the host.
• Permissions: A root process writing to a bind-mounted volume creates root-owned files on the host. Your host user (UID 1000) can’t edit or delete them without sudo.
• Least privilege: Same principle that applies everywhere else. Production containers should not run as root.

Know Your Base Image

Before creating a user, check whether the image already ships one. Some official images include a non-root user out of the box:

docker run --rm node id
# uid=1000(node) gid=1000(node) groups=1000(node)

Method 1: Add Users in the Dockerfile (Recommended)

Building users into the image is the durable approach. Users belong to images; containers inherit them. This survives restarts, redeployments, and docker compose up cycles.

Create a Non-Root User with useradd

The hardened pattern uses --no-log-init, pinned UID/GID, and a non-login shell:

FROM ubuntu:24.04

# Create a dedicated app user with a pinned UID/GID.
# 1001 leaves 1000 free to match the host user in bind mounts.
RUN groupadd -g 1001 appgroup && \
    useradd --no-log-init -u 1001 -g appgroup -m -s /usr/sbin/nologin appuser

# Run the container as the unprivileged user (numeric UID: survives /etc/passwd changes)
USER 1001:1001
WORKDIR /home/appuser

Flag breakdown:

You can parameterize UID/GID via build args. See ARG and ENV in Docker for the full pattern.

The Alpine Variant: adduser and addgroup

Alpine uses busybox adduser/addgroup, not the shadow-utils useradd. The flags are different:

FROM ubuntu:24.04

RUN groupadd -g 1001 appgroup && \
    useradd --no-log-init -u 1001 -g appgroup -m -s /usr/sbin/nologin appuser

USER 1001:1001
WORKDIR /home/appuser

FROM alpine:3.24

RUN addgroup -g 1001 appgroup && \
    adduser -D -u 1001 -G appgroup -s /bin/sh appuser

USER 1001:1001
WORKDIR /home/appuser

Alpine flag differences: -D = no password (equivalent to --disabled-password), -G = primary group, -s /bin/sh = shell (Alpine doesn’t have bash by default).

Lock It Down With Numeric USER 1001:1001

Docker’s own guidance recommends numeric UIDs:

# Good: survives /etc/passwd changes, no name resolution needed
USER 1001:1001

# Works but fragile: depends on /etc/passwd entry existing
USER appuser

When you specify a group (the :1001 part), the user gets only that group. No supplementary groups from /etc/group. This is usually what you want for a service account.

Set File Ownership with COPY --chown

Use COPY --chown to set ownership at build time instead of running chown in a separate RUN layer:

COPY --chown=1001:1001 app/ /home/appuser/app/
USER 1001:1001

COPY --chown accepts names or numeric UID/GID. Names require /etc/passwd resolution during the build. If the user doesn’t exist yet at that layer, the build fails. Numeric UIDs are safer and more portable.

For keeping Dockerfile layers lean, see copying multiple files in a single Dockerfile layer.

Multi-Stage Builds: Build as Root, Run as User

Multi-stage builds let you install packages and compile as root in a build stage, then copy only the artifacts into a clean runtime stage running as a non-root user:

# Build stage: runs as root, installs dependencies
FROM ubuntu:24.04 AS builder
RUN apt-get update && apt-get install -y --no-install-recommends build-essential
COPY . /src
WORKDIR /src
RUN make build

# Runtime stage: minimal image, non-root user
FROM ubuntu:24.04
RUN groupadd -g 1001 appgroup && \
    useradd --no-log-init -u 1001 -g appgroup -m -s /usr/sbin/nologin appuser
COPY --chown=1001:1001 --from=builder /src/app /home/appuser/app
USER 1001:1001
WORKDIR /home/appuser
CMD ["./app"]

The runtime image never has build-essential, source code, or build artifacts. Smaller attack surface, smaller image.

Method 2: Add Users at Runtime (Debugging Only)

Runtime user changes are temporary and useful only for debugging or one-off tasks. They live in the writable container layer and are lost when the container is recreated.

docker run -u / --user and --group-add

The -u / --user flag overrides the container’s default user at runtime. Numeric IDs don’t require an /etc/passwd entry:

# Run as UID 1001 with GID 1001
docker run --rm -it -u 1001:1001 myimage sh

# Add supplementary group 2000 (e.g., a shared volume group)
docker run --rm -it --user 1001:1001 --group-add 2000 myimage id

# Accepted formats:
#   -u user          # looked up in /etc/passwd
#   -u user:group    # both looked up
#   -u uid           # numeric, no lookup needed
#   -u uid:gid       # numeric, no lookup needed
#   -u user:gid      # mixed
#   -u uid:group     # mixed

This is useful for testing whether your app works as a non-root user before committing the change to the Dockerfile.

Inspect as Another User With docker exec -u

Instead of modifying a running container, use docker exec -u to run commands as a different user:

# Open a shell as appuser inside a running container
docker exec -it -u appuser mycontainer sh

# Run a single command as a specific UID
docker exec -u 1001:1001 mycontainer whoami
# appuser

# Check what files the app user can access
docker exec -u 1001:1001 mycontainer ls -la /app

This doesn’t modify the container — you’re just running a process as a different user. Great for diagnosing permission issues. For debugging container logs, see redirecting Docker logs to a single file.

Method 3: Map Host UID/GID to Fix Volume Permissions

This is the section that solves the bind-mount ownership problem from the intro. The core issue: container UID 0 (root) writes files to a mounted volume, and the host sees root-owned files that your host user (UID 1000) can’t edit.

The fix: pin the app UID to match the host user.

Build-Arg UID/GID Mapping

Pass the host user’s UID/GID at build time:

FROM ubuntu:24.04

ARG USER_ID=1000
ARG GROUP_ID=1000

RUN groupadd -g "$GROUP_ID" appgroup && \
    useradd --no-log-init -u "$USER_ID" -g "$GROUP_ID" -m -s /usr/sbin/nologin appuser

USER "$USER_ID:$GROUP_ID"

Build with your host user’s IDs:

docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t myapp .

The default of 1000 matches the standard first user on most Linux systems. On a single-user VPS, this is almost always correct. For more on build args, see ARG and ENV in Docker.

Docker Compose: user, group_add, and PUID/PGID

The Compose spec supports user and group_add directly. No version: key needed (it’s obsolete in Compose V2), and the command is docker compose, not docker-compose:

services:
  app:
    build: .
    user: "1001:1001"
    group_add:
      - "2000"
    volumes:
      - .:/app
    environment:
      - USER_ID=${USER_ID:-1001}
      - GROUP_ID=${GROUP_ID:-1001}

docker compose up -d --build

For a single-user VPS, hard-code user: "1000:1000" to match the ubuntu deploy user. The ${UID}/${GID} shell-export trick that some tutorials recommend breaks on macOS and Docker Desktop where the VM’s UIDs differ.

If you’re setting up Docker for the first time, see installing Docker on Ubuntu ARM.

Privilege Escalation Done Right: gosu Instead of sudo

The old advice was to install sudo in your image and add users to the sudo group. Docker’s own best practices now say to avoid this:

Avoid installing or using sudo as it has unpredictable TTY and signal-forwarding behavior. Instead, use gosu. — Docker build best practices

The gosu pattern (same as the official Postgres image) starts the entrypoint as root, fixes ownership of data directories, then drops to the app user:

FROM ubuntu:24.04

RUN apt-get update && \
    apt-get install -y --no-install-recommends gosu && \
    rm -rf /var/lib/apt/lists/*

RUN groupadd -g 1001 appgroup && \
    useradd --no-log-init -u 1001 -g appgroup -m appuser

COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["docker-entrypoint.sh"]

#!/bin/sh
set -e

# If running as root, fix ownership and drop to appuser
if [ "$(id -u)" = "0" ]; then
    chown -R appuser:appgroup /data
    exec gosu appuser "$@"
fi

exec "$@"

The container starts as root (so it can chown the data volume), then exec gosu appuser replaces the process with the unprivileged user. The app never runs as root.

Advanced Hardening: Userns-Remap and Rootless Docker

The USER instruction handles most cases. If you need stronger isolation (multi-tenant hosts, untrusted images, compliance requirements), two options exist:

User-Namespace Remapping

Maps container root (UID 0) to an unprivileged host UID. Add to /etc/docker/daemon.json:

{ "userns-remap": "default" }

sudo systemctl restart docker
id dockremap                              # daemon-created remap user
grep dockremap /etc/subuid /etc/subgid    # verify 65536-range subordinate IDs

Caveats:

• Enable on a fresh install only — it masks existing images and containers. You’ll need to re-pull everything.
• Per-container opt-out: docker run --userns=host (but this has side effects on file ownership).
• --privileged requires --userns=host; mknod is denied in user namespaces.
• Bind-mount ownership must be pre-arranged — the remapped UID on the host won’t match your expectations unless you plan for it.

Rootless Mode

Runs the Docker daemon itself as an unprivileged user. Prerequisites: newuidmap/newgidmap and at least 65,536 subordinate UIDs in /etc/subuid and /etc/subgid.

# Install the rootless setup tool
dockerd-rootless-setuptool.sh install

# Start the rootless daemon
systemctl --user start docker

Docker 29.5.0 made gvisor-tap-vsock the default rootless network driver, which improves compatibility.

When to bother: If you’re running untrusted images, hosting for multiple users, or have compliance requirements. For a single-user VPS running your own images, USER in the Dockerfile is enough. For more on Docker security, see hardening Docker on a Hetzner VPS.

Verify Before You Deploy

Don’t assume — verify. Run these commands after building and after every deploy:

Quick verification script:

# After build — confirm the image's default user
docker run --rm myimage id

# Inspect without running
docker create --name tmp myimage && docker inspect --format '{{.Config.User}}' tmp && docker rm tmp

# Inside a running container
docker exec -it mycontainer id

# Bind-mount ownership check (host side)
docker exec mycontainer touch /app/check.txt && ls -l ./check.txt
# Should show your host UID (e.g., 1000), not root

Troubleshooting: Common Permission Failure Modes

For more Docker commands and patterns, bookmark the essential Docker commands reference.

Quick Reference: User Creation Commands

TL;DR

Some other Docker articles that can help you in your Docker journey:

• Copy Multiple Files in One Layer Using a Dockerfile
• Install Docker & Docker-compose for Ubuntu ARM
• Redirect Docker Logs to a Single File
• Environment Variables ARG and ENV in Docker