Problem description


Files written in host volume created by root user in Docker containers are also owned by root on the host. Use Docker namespaces to map your host user to the container root.

Docker host volumes

In local development using languages and frameworks that support hot code reloading it is common to share a directory on your host system with the Docker container. This can be achieved using built-in Docker feature called host volumes. This way you don’t have to rebuild the image every time you change make a change.

Docker is a Linux only solution based on Linux Containers. It is possible to run Docker on Mac OS or Windows hosts but underneath it uses a virtual machine running Linux with docker deamon. In these systems Docker host volumes are implemented using NFS or some other customer solutions.

When Docker runs natively on a Linux host then it can directly access files on the host filesystem.

Host volumes on Linux hosts

By default there’s no mapping of permissions and ownership between Linux host and Docker container. In a Docker container you see the same permissions of files on host volumes as on a host. What’s more interesting and problematic is that it works the other way too.


Let’s create a directory with 2 files. All commands in this example are executed on the Linux host.

$ mkdir example
$ cd example
$ touch file1 file2
$ chmod 777 file2
$ ls -l
total 0
-rw-rw-r-- 1 jan jan 0 Jun 10 10:22 file1
-rwxrwxrwx 1 jan jan 0 Jun 10 10:22 file2

Now check how Docker container sees them.

$ docker run --rm -v $PWD:/example -w /example alpine /bin/ls -l
total 0
-rw-rw-r--    1 1000     1000             0 Jun 10 17:22 file1
-rwxrwxrwx    1 1000     1000             0 Jun 10 17:22 file2

You can see that while permissions (-rw-rw-r-- and -rwxrwxrwx) are unchanged the ownership columns has changed from jan to 1000.

While the output is different the actual ownership hasn’t really changed. 1000 is my UID and GID

It can be verified using id command:

$ id
uid=1000(jan) gid=1000(jan) groups=1000(jan),4(adm),24(cdrom),27(sudo),30(dip),46(plugdev),113(lpadmin),128(sambashare),999(docker)

In the Docker container my user and group jan doesn’t exist thus ls is not able to map the files ownership IDs to user labels.

As I said earlier most Docker images use root default user by default. Alpine is no exception here:

$ docker run --rm alpine whoami

So what happens if we create a file in the host volume?

$ docker run --rm -v $PWD:/example -w /example alpine touch file3
$ ls -l
total 0
-rw-rw-r-- 1 jan  jan  0 Jun 10 10:22 file1
-rwxrwxrwx 1 jan  jan  0 Jun 10 10:22 file2
-rw-r--r-- 1 root root 0 Jun 10 10:40 file3

The file has root:root permissions!

This behaviour is usually unexpected. For a practical example please see the previous post about bootstrapping Rails with Docker.


Thanks to user namespace it is possible to remap UID and GIDs in the containers.

Namespacing isolates Docker files such as images and container files in /var/lib/docker/.

All existing images and containers will not be available after enabling user namespace.

From the docs:

Enabling userns-remap effectively masks existing image and container layers, as well as other Docker objects within /var/lib/docker/. This is because Docker needs to adjust the ownership of these resources and actually stores them in a subdirectory within /var/lib/docker/. It is best to enable this feature on a new Docker installation rather than an existing one.

User namespace and all the other namespaces were created to protect hosts, limiting processes in containers from accessing host resources.

It is usually done by assigning some very high UID and GID to be sure that they don’t interfere with IDs on the host.

In this scenario we want to use (abuse?) this system to map root (with ID 0) to our local Linux user.

Step 1 - create user namespace

Using id find out what’s your UID and the effective (primary) GID. Usually on popular distributions like Ubuntu both are equal 1000.

$ id
uid=1000(jan) gid=1000(jan) groups=1000(jan),4(adm),24(cdrom),27(sudo),30(dip),46(plugdev),113(lpadmin),128(sambashare),999(docker)
$ id -u
$ id -g

Edit /etc/subuid and /etc/subgid to set user and group namespace respectively. In my setup on Ubuntu these files exist by default defining namespace equal to my username.

Namespace definition format is described in more details in the docs. It is a colon seperated triplet describing:

  • namespace name
  • first ID in the namespace
  • number of possible IDs in the namespace

In my case both /etc/subuid and /etc/subgid have the same content:


65536 doesn’t mean anything, it’s just a very high value.

Step 2 - enable namespace in Docker

Edit /etc/docker/daemon.json using the following template (you might need to create this file if it doesn’t exist):

  "userns-remap": "NAMESPACE_NAME"

In my case it is:

  "userns-remap": "jan"

Now restart Docker. On Ubuntu by default it can be done using service docker restart.

As I mentioned earlier all your previous containers are images are not available after enabling namespace. They are masked, not deleted. You can go back to the default namespace by reverting this change.


Given the file structure from the previous section:

$ ls -l 
total 0
-rw-rw-r-- 1 jan  jan  0 Jun 10 10:22 file1
-rwxrwxrwx 1 jan  jan  0 Jun 10 10:22 file2
-rw-r--r-- 1 root root 0 Jun 10 10:40 file3

Let’s check how Docker perceives the files now:

docker run --rm -v $PWD:/example -w /example alpine /bin/ls -l
total 0
-rw-rw-r--    1 root     root             0 Jun 10 17:22 file1
-rwxrwxrwx    1 root     root             0 Jun 10 17:22 file2
-rw-r--r--    1 nobody   nobody           0 Jun 10 17:40 file3

Great! Now my user and group are properly mapped inside the container to root.

Notice that container root’s file3 is marked as nobody’s.

Final check - write inside the container.

$ docker run --rm -v $PWD:/example -w /example alpine touch file4
$ ls -l
total 0
-rw-rw-r-- 1 jan  jan  0 Jun 10 10:22 file1
-rwxrwxrwx 1 jan  jan  0 Jun 10 10:22 file2
-rw-r--r-- 1 root root 0 Jun 10 10:40 file3
-rw-r--r-- 1 jan  jan  0 Jun 10 11:52 file4

file4 was mapped to jan in the host as expected.