OverlayFS has a workdir option, beside two other directories lowerdir and upperdir, which needs to be an empty directory.

Unfortunately the kernel documentation of overlayfs does not talk much about the purpose of this option.

The "workdir" needs to be an empty directory on the same filesystem as upperdir.

For readonly overlays the workdir might be ommittet among the upperdir. This give me the clue that it has to do with writing the merged files.

Please explain what's happening in the workdir when files are written or changed in the merged directory. Why is the writable upperdir not enough?

  • 6
    My guess: When a lower file is to be modified, it is copied (a non-atomic operation) to workdir and then atomically moved into the right place in upper. Thus, other processes will either open the (complete) lower file or (after the switch) the complete upper file, never a halfway-done file. Commented Mar 8, 2020 at 14:33

2 Answers 2


The workdir option is required, and used to prepare files before they are switched to the overlay destination in an atomic action (the workdir needs to be on the same filesystem as the upperdir).

Source: http://windsock.io/the-overlay-filesystem/

I would hazard a guess that "the overlay destination" means upperdir.

So... certain files (maybe "whiteout" files?) are non-atomically created and configured in workdir and then atomically moved into upperdir.

  • The link is broken
    – xOneca
    Commented Jun 11, 2023 at 12:42

Because when you delete a file which is on lowerdir, this information will be stored in the workdir.

  • 2
    Hm, but when I delete files in the merged directory, the workdir remains empty but there are files shown in the upperdir with a c flag (c--------- 1 root root 0, 0 Nov 19 18:22 ivebeendeleted) when they've been "overlay-deleted" from the lower dir. (The same file remains in the lowerdir of course.) Commented Nov 19, 2016 at 17:55
  • 4
    I think when you delete a file, a "whiteout" file is created and this is stored in the upperdir, not the workdir. The whiteout file is a character device (with "c" flag)
    – ejm
    Commented Sep 23, 2017 at 8:21

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .