---
description: Learn how to optimize your use of OverlayFS driver.
keywords: container, storage, driver, OverlayFS, overlay2, overlay
title: OverlayFS storage driver
aliases:
  - /storage/storagedriver/overlayfs-driver/
---

OverlayFS is a union filesystem.

This page refers to the Linux kernel driver as `OverlayFS` and to the Docker
storage driver as `overlay2`.

> [!NOTE]
>
> For `fuse-overlayfs` driver, check [Rootless mode documentation](/manuals/engine/security/rootless.md).

## Prerequisites

OverlayFS is the recommended storage driver, and supported if you meet the following
prerequisites:

- Version 4.0 or higher of the Linux kernel, or RHEL or CentOS using
  version 3.10.0-514 of the kernel or higher.
- The `overlay2` driver is supported on `xfs` backing filesystems,
  but only with `d_type=true` enabled.

  Use `xfs_info` to verify that the `ftype` option is set to `1`. To format an
  `xfs` filesystem correctly, use the flag `-n ftype=1`.

- Changing the storage driver makes existing containers and images inaccessible
  on the local system. Use `docker save` to save any images you have built or
  push them to Docker Hub or a private registry before changing the storage driver,
  so that you don't need to re-create them later.

## Configure Docker with the `overlay2` storage driver

<a name="configure-docker-with-the-overlay-or-overlay2-storage-driver"></a>

Before following this procedure, you must first meet all the
[prerequisites](#prerequisites).

The following steps outline how to configure the `overlay2` storage driver.

1. Stop Docker.

   ```console
   $ sudo systemctl stop docker
   ```

2. Copy the contents of `/var/lib/docker` to a temporary location.

   ```console
   $ cp -au /var/lib/docker /var/lib/docker.bk
   ```

3. If you want to use a separate backing filesystem from the one used by
   `/var/lib/`, format the filesystem and mount it into `/var/lib/docker`.
   Make sure to add this mount to `/etc/fstab` to make it permanent.

4. Edit `/etc/docker/daemon.json`. If it doesn't yet exist, create it. Assuming
   that the file was empty, add the following contents.

   ```json
   {
     "storage-driver": "overlay2"
   }
   ```

   Docker doesn't start if the `daemon.json` file contains invalid JSON.

5. Start Docker.

   ```console
   $ sudo systemctl start docker
   ```

6. Verify that the daemon is using the `overlay2` storage driver.
   Use the `docker info` command and look for `Storage Driver` and
   `Backing filesystem`.

   ```console
   $ docker info

   Containers: 0
   Images: 0
   Storage Driver: overlay2
    Backing Filesystem: xfs
    Supports d_type: true
    Native Overlay Diff: true
   <...>
   ```

Docker is now using the `overlay2` storage driver and has automatically
created the overlay mount with the required `lowerdir`, `upperdir`, `merged`,
and `workdir` constructs.

Continue reading for details about how OverlayFS works within your Docker
containers, as well as performance advice and information about limitations of
its compatibility with different backing filesystems.

## How the `overlay2` driver works

OverlayFS layers two directories on a single Linux host and presents them as
a single directory. These directories are called layers, and the unification
process is referred to as a union mount. OverlayFS refers to the lower directory
as `lowerdir` and the upper directory as `upperdir`. The unified view is exposed
through its own directory called `merged`.

The `overlay2` driver natively supports up to 128 lower OverlayFS layers. This
capability provides better performance for layer-related Docker commands such
as `docker build` and `docker commit`, and consumes fewer inodes on the backing
filesystem.

### Image and container layers on-disk

After downloading a five-layer image using `docker pull ubuntu`, you can see
six directories under `/var/lib/docker/overlay2`.

> [!WARNING]
>
> Don't directly manipulate any files or directories within
> `/var/lib/docker/`. These files and directories are managed by Docker.