---
description: Learn how to optimize your use of Btrfs driver.
keywords: container, storage, driver, Btrfs
title: BTRFS storage driver
aliases:
  - /storage/storagedriver/btrfs-driver/
---

Btrfs is a copy-on-write filesystem that supports many advanced storage
technologies, making it a good fit for Docker. Btrfs is included in the
mainline Linux kernel.

Docker's `btrfs` storage driver leverages many Btrfs features for image and
container management. Among these features are block-level operations, thin
provisioning, copy-on-write snapshots, and ease of administration. You can
combine multiple physical block devices into a single Btrfs filesystem.

This page refers to Docker's Btrfs storage driver as `btrfs` and the overall
Btrfs Filesystem as Btrfs.

> [!NOTE]
>
> The `btrfs` storage driver is only supported with Docker Engine CE on SLES,
> Ubuntu, and Debian systems.

## Prerequisites

`btrfs` is supported if you meet the following prerequisites:

- `btrfs` is only recommended with Docker CE on Ubuntu or Debian systems.

- Changing the storage driver makes any containers you have already
  created inaccessible on the local system. Use `docker save` to save containers,
  and push existing images to Docker Hub or a private repository, so that you
  do not need to re-create them later.

- `btrfs` requires a dedicated block storage device such as a physical disk. This
  block device must be formatted for Btrfs and mounted into `/var/lib/docker/`.
  The configuration instructions below walk you through this procedure. By
  default, the SLES `/` filesystem is formatted with Btrfs, so for SLES, you do
  not need to use a separate block device, but you can choose to do so for
  performance reasons.

- `btrfs` support must exist in your kernel. To check this, run the following
  command:

  ```console
  $ grep btrfs /proc/filesystems

  btrfs
  ```

- To manage Btrfs filesystems at the level of the operating system, you need the
  `btrfs` command. If you don't have this command, install the `btrfsprogs`
  package (SLES) or `btrfs-tools` package (Ubuntu).

## Configure Docker to use the btrfs storage driver

This procedure is essentially identical on SLES and Ubuntu.

1. Stop Docker.

2. Copy the contents of `/var/lib/docker/` to a backup location, then empty
   the contents of `/var/lib/docker/`:

   ```console
   $ sudo cp -au /var/lib/docker /var/lib/docker.bk
   $ sudo rm -rf /var/lib/docker/*
   ```

3. Format your dedicated block device or devices as a Btrfs filesystem. This
   example assumes that you are using two block devices called `/dev/xvdf` and
   `/dev/xvdg`. Double-check the block device names because this is a
   destructive operation.

   ```console
   $ sudo mkfs.btrfs -f /dev/xvdf /dev/xvdg
   ```

   There are many more options for Btrfs, including striping and RAID. See the
   [Btrfs documentation](https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices).

4. Mount the new Btrfs filesystem on the `/var/lib/docker/` mount point. You
   can specify any of the block devices used to create the Btrfs filesystem.

   ```console
   $ sudo mount -t btrfs /dev/xvdf /var/lib/docker
   ```

   > [!NOTE]
   >
   > Make the change permanent across reboots by adding an entry to
   > `/etc/fstab`.

5. Copy the contents of `/var/lib/docker.bk` to `/var/lib/docker/`.

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

6. Configure Docker to use the `btrfs` storage driver. This is required even
   though `/var/lib/docker/` is now using a Btrfs filesystem.
   Edit or create the file `/etc/docker/daemon.json`. If it is a new file, add
   the following contents. If it is an existing file, add the key and value
   only, being careful to end the line with a comma if it isn't the final
   line before an ending curly bracket (`}`).

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

   See all storage options for each storage driver in the
   [daemon reference documentation](/reference/cli/dockerd/#options-per-storage-driver)