Skip to content
Tutorials Center
My learning

Topics

Lesson 50 of 111 ยท Data and Volumes

Volume Drivers and Remote Storage

Learn how Docker volume drivers work: local driver options for tmpfs, bind and NFS volumes, CIFS shares, third-party plugins, Compose driver_opts and performance notes.

So far, a volume has been "a folder that Docker keeps on the host". That is only the default. Behind every volume sits a volume driver, a piece of code that knows how to create the storage, mount it into containers, and delete it. The built-in driver is called local. Its name is misleading, because the local driver can also mount a network share, a RAM disk or any folder, by passing the same options the Linux mount command takes. Third-party drivers go further and talk to cloud disks or storage clusters.

This lesson explains how drivers are chosen, what you can do with the local driver alone (it is a lot), how NFS and CIFS volumes look and fail, what plugin drivers are, and what to keep in mind for speed.

Where the driver comes from

Every volume has a Driver field. If you do not pick one, you get local:

CONSOLE
$ docker volume create demo
demo
$ docker volume inspect demo -f '{{.Driver}} {{.Scope}} {{.Mountpoint}}'
local local /var/lib/docker/volumes/demo/_data

You choose a different driver with --driver (-d) when creating the volume, and pass driver-specific settings with --opt (-o):

TEXT
docker volume create --driver <name> --opt key=value --opt key2=value2 <volume-name>
TEXT
  container โ”€โ”€ mounts โ”€โ”€โ–ถ volume "db-data" โ”€โ”€ driver: local  โ”€โ”€โ–ถ folder on the host
                                          โ””โ”€ driver: local + type=nfs โ”€โ”€โ–ถ NFS server
                                          โ””โ”€ driver: plugin  โ”€โ”€โ–ถ cloud disk / cluster

Creating a volume does not mount anything yet. Docker records the driver and options, and the mount happens when a container starts. That is why a broken option shows up as an error from docker run, not from docker volume create:

CONSOLE
$ docker volume create --driver local --opt type=tmpfs --opt device=tmpfs --opt o=size=bad broken
broken
$ docker run --rm -v broken:/v alpine true
docker: Error response from daemon: error while mounting volume '/var/lib/docker/volumes/broken/_data': failed to mount local volume: mount tmpfs:/var/lib/docker/volumes/broken/_data, data: size=bad: invalid argument

Read these error messages closely. The local driver reports the exact mount call it tried: the filesystem source, the target, and the options (data:). Most failures are typos or unreachable servers.

The local driver's three options

The local driver understands the same three options as the Linux mount -t <type> -o <options> <device> <target> command:

Option Meaning
type Filesystem type: tmpfs, nfs, nfs4, cifs, btrfs, ext4, none (for bind), ...
device What to mount: a server and path, a block device, a host folder, or just tmpfs
o Comma-separated mount options, such as size=16m, addr=10.0.0.5,rw, bind, ro

If you give no options, the driver creates a plain folder under /var/lib/docker/volumes/. With options it mounts whatever you describe. The rest of this section is just three recipes.

A RAM-backed volume

CONSOLE
$ docker volume create --driver local --opt type=tmpfs --opt device=tmpfs --opt o=size=16m ramdisk
ramdisk
$ docker volume inspect ramdisk
[
    {
        "CreatedAt": "2026-10-23T14:36:21Z",
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/var/lib/docker/volumes/ramdisk/_data",
        "Name": "ramdisk",
        "Options": {
            "device": "tmpfs",
            "o": "size=16m",
            "type": "tmpfs"
        },
        "Scope": "local"
    }
]
$ docker run --rm -v ramdisk:/v alpine sh -c 'df -h /v; mount | grep " /v "'
Filesystem                Size      Used Available Use% Mounted on
tmpfs                    16.0M         0     16.0M   0% /v
tmpfs on /v type tmpfs (rw,relatime,size=16384k)

This differs from a tmpfs mount in one way: it has a name. Several containers can mount ramdisk and share the in-memory folder, one at a time or together, as long as the Docker host keeps it mounted. Unlike --tmpfs, this mount is a normal volume without the noexec flag you saw in the previous lesson. The 16 MB limit works exactly as before:

CONSOLE
$ docker run --rm -v ramdisk:/v alpine sh -c 'dd if=/dev/zero of=/v/f bs=1M count=20'
dd: error writing '/v/f': No space left on device
17+0 records in
16+0 records out
16777216 bytes (16.0MB) copied, 0.015001 seconds, 1.0GB/s

A named volume over a host folder

With type=none and o=bind you get a volume whose data lives at a folder you chose. The folder must exist and the path must be absolute:

CONSOLE
$ mkdir -p /srv/shared && echo hi > /srv/shared/f.txt
$ docker volume create --driver local --opt type=none --opt o=bind --opt device=/srv/shared shared
shared
$ docker run --rm -v shared:/v alpine cat /v/f.txt
hi

Why do this instead of a plain bind mount? Because the application's Compose file or docker run line only mentions the volume name shared. The decision where the data lives moves to the host's own volume definition, so the same file works on a laptop and on a server with a special data disk.

An NFS volume

NFS lets many hosts read and write the same files. The server details go into the volume:

CONSOLE
$ docker volume create --driver local \
    --opt type=nfs \
    --opt o=addr=192.0.2.10,rw,nfsvers=4 \
    --opt device=:/exports/data \
    nfs-data

(This is a read-only example: it needs an NFS server, and 192.0.2.10 is a reserved documentation address.) Note the odd device=:/exports/data: the part before the colon is empty because the server is given in addr=. With a hostname you can also write device=nfs.example.com:/exports/data together with a matching addr. When the server cannot be reached, the failure is reported on docker run, as before. We tried it against an address with no server behind it:

CONSOLE
$ docker run --rm -v nfs-data:/v alpine ls /v
docker: Error response from daemon: error while mounting volume '/var/lib/docker/volumes/nfs-data/_data': failed to mount local volume: mount :/exports/data:/var/lib/docker/volumes/nfs-data/_data, flags: 0x1, data: addr=192.0.2.10: connection refused

Common NFS problems: the Docker host has no NFS client packages (nfs-common on Debian, nfs-utils on RHEL), the server's export list does not allow the host, the firewall blocks port 2049, or the server runs NFSv3 while you asked for v4. Because the mount happens on the Docker host, the container needs no NFS software at all.

A CIFS (SMB) volume

For a Windows or Samba share use type=cifs. Credentials are part of the options, which is a problem, see the warning below.

Terminal
# read-only example: needs a real SMB server and the cifs-utils package on the host
docker volume create --driver local \
  --opt type=cifs \
  --opt device=//fileserver.example.com/projects \
  --opt o=addr=fileserver.example.com,username=svc-docker,password=CHANGE_ME,uid=1000,gid=1000,vers=3.0 \
  projects

The uid and gid options set the owner that files appear to have inside the container, which is how you make a share writable by a non-root application user.

Volume options are stored in plain text and shown by docker volume inspect. A password in o=... is visible to everyone who can run Docker commands on that host. Prefer a credentials file readable only by root (o=credentials=/etc/smb-docker.cred,...) or a mount done by the host's own configuration.

Compose and driver options

In Compose, the same settings go under driver and driver_opts of a top-level volume. Name the driver explicitly:

YAML
services:
  app:
    image: alpine
    command: sleep 300
    volumes:
      - ramdisk:/ram
      - shared:/shared

volumes:
  ramdisk:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs
      o: size=8m
  shared:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /srv/shared

We brought this up with docker compose up -d. Inside the container:

CONSOLE
$ docker exec app sh -c 'df -h /ram | tail -1; cat /shared/hello.txt'
tmpfs                     8.0M         0      8.0M   0% /ram
from-host

One more Compose detail: Compose adds the project name to the volume name (myproject_ramdisk) and writes labels on it. A volume declared with external: true is not created or deleted by Compose; you create it yourself with the driver options, which suits NFS volumes shared between projects.

Options are fixed when the volume is created. If you change driver_opts in a Compose file, the existing volume keeps its old settings. Remove the volume (docker compose down -v, or docker volume rm) and create it again. Check the stored settings with docker volume inspect.

Volume plugins

The local driver cannot talk to a cloud API or a storage cluster. For that there are volume plugins: separate programs that register with the Docker daemon, either as managed plugins installed with docker plugin install or as processes listening on a socket. Examples include drivers for Amazon EBS and EFS, Azure Files, Google persistent disks, Ceph, GlusterFS, NetApp and StorageOS-style systems. Because they are third-party code running with high privileges, install only plugins from sources you trust.

A managed plugin is installed like this (read-only example; the plugin name is made up):

Terminal
docker plugin install example/storage-plugin:1.0 --grant-all-permissions
docker volume create --driver example/storage-plugin:1.0 --opt size=20GB cloud-data
docker plugin ls

On a fresh machine there are none installed. The daemon reports exactly one volume driver:

CONSOLE
$ docker plugin ls
ID        NAME      DESCRIPTION   ENABLED
$ docker info -f '{{json .Plugins.Volume}}'
["local"]

Naming a driver that is not installed fails right away, at creation:

CONSOLE
$ docker volume create --driver no-such-driver x
Error response from daemon: create x: error looking up volume plugin no-such-driver: plugin "no-such-driver" not found

An example from history: REX-Ray

REX-Ray was a well-known storage plugin from the early days of Docker plugins. It let a container use block volumes from Amazon EBS, OpenStack Cinder, Google persistent disks and other backends, and it could re-attach a volume on another host when the container moved. You installed it as a managed plugin and passed the cloud credentials as plugin settings (read-only example, placeholder values):

Terminal
docker plugin install rexray/ebs REXRAY_PREEMPT=true \
  EBS_ACCESSKEY=<access-key> EBS_SECRETKEY=<secret-key> --grant-all-permissions
docker volume create --driver rexray/ebs --opt size=10 db-data
docker run -d -v db-data:/var/lib/mysql mysql:8.4

The project is no longer maintained, so treat it as something to recognize in older setups. Today the same job is done by the cloud provider's own plugin or CSI driver, or by Kubernetes (Persistent Volumes). The pattern is still worth knowing: the plugin receives the --opt values, creates or attaches a disk, and mounts it where the container expects it. Never type real access keys on a command line, because they end up in shell history; prefer instance roles or a secrets manager.

Plugin-specific --opt keys are defined by the plugin's own documentation; Docker only passes them through.

Performance and reliability notes

  • A volume on a local disk is the fastest durable option. Network volumes add latency to every file operation. A database on NFS with the wrong options can be both slow and unsafe; many databases explicitly do not support it. Prefer local SSD volumes for databases and use the database's own replication for redundancy.
  • Network volumes are fine for shared files: media uploads, build outputs, configuration, shared read-mostly content.
  • Many small files hurt most. Metadata calls (open, stat, rename) are network round trips on NFS or CIFS. A large node_modules folder or a PHP framework's cache on a network share can be many times slower than a local volume.
  • Hard versus soft mounts. The NFS soft option makes operations fail on timeouts instead of hanging. That avoids a stuck container, but a failed write can silently lose data. Hanging (hard, the default) is safer for writes.
  • Mounts happen on the host at container start. If the share is unreachable, the container does not start. If the share goes away later, processes inside can block in the kernel, uninterruptible even by docker stop until the server returns.
  • On Docker Desktop, the local driver runs inside the Docker VM, not on your Windows or macOS system. A device= path must exist there. A Windows path such as C:/work/shared is translated for you for bind-type volumes, but NFS servers must be reachable from the VM.
  • tmpfs-type volumes count as memory against the host, exactly like a tmpfs mount.

Choosing a storage strategy

Goal Choice
Default persistent storage Plain named volume (local, no options)
Fast temporary shared data local volume with type=tmpfs and a size
Data on a specific disk, with a clean Compose file local volume with type=none,o=bind
Shared files across hosts NFS or CIFS through local options
Cloud-native disks, replicated storage A volume plugin from your cloud or storage vendor

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the built-in local volume driver support besides plain folders on the host?

    The local driver accepts the same type, device and o values as the Linux mount command, so it can mount tmpfs, NFS, CIFS and a host folder.
  2. 2. You created an NFS volume pointing at a server that is down. When do you first see an error?

    Creating a volume only records the driver and options. The actual mount, and any failure, happens when a container starts.
  3. 3. Why is a password inside --opt o=...,password=... a bad idea?

    Anyone who can run docker volume inspect on that host can read the options. Use a root-only credentials file instead.
  4. 4. You change driver_opts in an existing Compose file and run docker compose up -d again. The volume still has the old options. Why?

    Docker does not modify an existing volume. Remove it (docker compose down -v or docker volume rm) so it is created again with the new settings.
  5. 5. Which workload is generally a poor fit for an NFS-backed volume?

    Databases are sensitive to latency and locking semantics. Use local fast storage and the database's replication or backup tools instead.

Summary

  • Every volume has a driver. The default local driver can also mount tmpfs, host folders, NFS and CIFS through type, device and o options.
  • Create with docker volume create --driver ... --opt ...; the mount (and any error) happens when a container starts.
  • In Compose use driver: local and driver_opts; volume settings never change after creation.
  • Plugins add cloud and cluster storage, but they run with high privileges, so install only trusted ones.
  • Network volumes suit shared files, not databases; many small files are slow; secrets in options are visible.

Next: Docker Networking