From Fedora Project Wiki

Self Container Change: This change will only affect users of the docker package.

Docker Overlay 2


Change the default Docker Storage to use OverlayFS via the overlay2 driver, for better performance.


  • Name: Lokesh Mandvekar
  • Name: Dan Walsh
  • Email:,
  • Release notes owner:
  • Product: Workstation, Atomic Host, Server

Current status

Detailed Description

Upstream docker is moving to overlay2 by default for its storage. We plan on following suit. (This is an updated driver for the OverlayFS filesystem, not a second overlay filesystem.) There are some performance advantages of overlay2 over devicemapper in memory sharing, which we would like to take advantage of. We now have SELinux support for Overlay file systems, so the security should be just as good.

Note: Overlay is not a Posix Compliant file system, so there could be problems with your containers running on overlay, so we want to make sure it is fairly easy to switch back to devicemapper.

Devicemapper out of the box, on Fedora Workstation, currently defaults to loopback devices for storage, which has a performance penalty, but this was the only way we were able to get docker to work right away. Switching to overlay2 will cause the storage to be shared with / and will eliminate this performance overhead. This is the way we will ship Fedora Workstation.

On Fedora atomic host and Fedora server we have been storing devicemapper storage on a separate partition. We plan on doing the same thing with overlay2. This means separate device will be mounted on /var/lib/docker. This will make it easier for someone to switch back to devicemapper, if overlay2 has problems.

Upgraded systems will not be effected.

If you want to switch from one storage to another take a look at the atomic storage commands.

We will write up release notes to cover this change. Along with a blog explaining the commands to switch back and forth.

Benefit to Fedora

Better performance of docker containers. Show that Fedora is leading the way in container development.


  • Proposal owners: Implementation of this Change
  • Other developers: N/A (not a System Wide Change)
  • Release engineering: N/A (not a System Wide Change)
  • Policies and guidelines: N/A (not a System Wide Change)
  • Trademark approval: N/A (not needed for this Change)

Upgrade/compatibility impact

N/A (not a System Wide Change)

How To Test

Install a fresh docker, make sure the default storage is on overlay,if installing on atomic host or Fedora Server, make sure the overlay file system is setup on a different partion, and it mounted after a reboot.

Make sure you can switch from overlay2 back to devicemapper using atomic storage commands. N/A (not a System Wide Change)

User Experience

N/A (not a System Wide Change) Users should not notice the change other then if they use the docker or atomic CLI to examine the storage.


N/A (not a System Wide Change)

Contingency Plan

  • Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change)
  • Contingency deadline: N/A (not a System Wide Change)
  • Blocks release? N/A (not a System Wide Change), Yes/No
  • Blocks product? product


N/A (not a System Wide Change)

Release Notes