Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Files in a Docker image keep root ownership after chown

Errorls -l in the container shows root root on files you chowned

Short answer

Three things make chown look broken. COPY and ADD create files owned by root unless you add --chown. On the legacy builder, anything changed after a VOLUME instruction is discarded. And --chown with a name needs that user in the image's /etc/passwd; numeric IDs always work.

  • Applies to Docker Engine 27, BuildKit, Dockerfile reference
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at who really owns the files in the built image.

    docker run --rm my-image ls -ln /app
  2. 2Match what you see, then jump to its fix

    1. 1Owner 0 0 on copied filesCOPY created the files as rootFix
    2. 2chown RUN step succeeds but the directory is root-owned at runtimeThe change comes after a VOLUME instructionFix
    3. 3Build fails resolving the user, or the owner is not what you namedThe user name is not in the image's /etc/passwdFix

What does the error look like?

  • ls -l in the container shows root root on files you chowned
  • Permission denied writing to a directory the app user should own

Cause 1 of 3

COPY created the files as root

1Check

The Dockerfile reference says that without --chown, files are created with UID and GID 0.

grep -n "COPY\|ADD\|USER" Dockerfile

2Fix

Set the owner on the COPY itself instead of a separate chown layer.

COPY --chown=1000:1000 . /app

3Verify

Rebuild and list the owner again.

docker build -t my-image . && docker run --rm my-image ls -ln /app

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The change comes after a VOLUME instruction

1Check

The reference says changes made to a volume after it is declared are discarded with the legacy builder, and kept with BuildKit.

docker buildx version; grep -n VOLUME Dockerfile

2Fix

Create the directory and set its owner before the VOLUME line, and use BuildKit.

RUN mkdir -p /data && chown 1000:1000 /data
VOLUME /data

3Verify

Run the image and list the directory owner.

docker run --rm my-image ls -ldn /data

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The user name is not in the image's /etc/passwd

1Check

Names are resolved from /etc/passwd and /etc/group in the container root filesystem; numeric IDs need no lookup. The reference also says --chown with --link needs numeric IDs.

docker run --rm my-image getent passwd appuser

2Fix

Create the user before the COPY, or use numeric IDs in --chown.

RUN useradd -u 1000 appuser
COPY --chown=appuser:appuser . /app

3Verify

Rebuild and check the owner column.

docker run --rm my-image ls -l /app

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Prefer COPY --chown over a separate RUN chown so ownership is set where the files are created.
  • Assign an explicit UID and GID to the app user, as the Docker best-practices page advises when IDs matter.
  • Declare VOLUME last, after directories exist with the right owner.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.