fuse-overlayfs is a user-space implementation of the overlay filesystem that Podman can use for its storage driver.
Here’s Podman creating a container and showing the fuse-overlayfs storage in action:
# Create a simple container
podman run -d --name my-test-container alpine:latest sleep 3600
# Inspect the container's storage
podman inspect my-test-container
# Look for the "GraphDriver" section. You should see something like:
# "GraphDriver": {
# "Data": {
# "MergedDir": "/var/lib/containers/storage/overlay/a1b2c3d4e5f6...",
# "UpperDir": "/var/lib/containers/storage/overlay/a1b2c3d4e5f6.../upper",
# "WorkDir": "/var/lib/containers/storage/overlay/a1b2c3d4e5f6.../work"
# },
# "Name": "fuse-overlayfs"
# }
This output shows the core components of the fuse-overlayfs storage driver for this specific container: MergedDir (the view of the container’s filesystem), UpperDir (where container-specific changes are written), and WorkDir (a temporary directory for overlay operations). The Name field explicitly confirms fuse-overlayfs is being used.
fuse-overlayfs is particularly useful in environments where you don’t have root privileges or need to run containers as a non-root user. It leverages FUSE (Filesystem in Userspace) to provide the overlay filesystem functionality without requiring kernel-level support for overlayfs itself, or at least without needing it to be enabled and configured system-wide for root. When running as root, Podman might prefer the kernel’s native overlay driver if available, as it generally offers better performance. However, fuse-overlayfs provides a robust fallback and is often the default for rootless Podman.
The fundamental problem fuse-overlayfs solves is providing copy-on-write (CoW) semantics for container images and layers in a flexible, often user-space, manner. An overlay filesystem works by stacking multiple directories. A lower directory (read-only image layers) is combined with an upper directory (container-writable layer). When a file is read, it appears as if it’s in a single merged filesystem. When a file is written, it’s copied from the lower layer to the upper layer (copy-on-write) and then modified there, leaving the original image layers untouched. The fuse-overlayfs implementation handles these operations through the FUSE kernel module and a user-space daemon.
The primary levers you control with fuse-overlayfs are related to its configuration within Podman and the underlying FUSE system. For most users, Podman handles the selection of the storage driver automatically based on the environment (rootful vs. rootless, available kernel modules). However, you can influence it through Podman’s configuration file, typically located at /etc/containers/storage.conf or ~/.config/containers/storage.conf.
Here’s a snippet of what storage.conf might look like to force fuse-overlayfs if you wanted to, though this is rarely necessary and usually indicates a problem with your default setup if you need to explicitly set it for rootful containers:
[storage]
driver = "fuse-overlayfs"
You’d then restart the Podman service or your rootless daemon. This setting tells Podman to use fuse-overlayfs as its primary storage driver. If you’re running rootless, fuse-overlayfs is often the default and might be invoked automatically without needing explicit configuration.
The fuse-overlayfs driver relies on the FUSE system. Ensure the fuse package is installed on your system. For example, on Debian/Ubuntu:
sudo apt update && sudo apt install fuse -y
On Fedora/CentOS/RHEL:
sudo dnf install fuse -y
If fuse-overlayfs is not working or is not being selected, a common issue is the FUSE kernel module not being loaded or the necessary user-space utilities being absent. Podman’s storage.conf also has options to define the mount_program which can be crucial. If you’re experiencing issues, you might see errors related to mount: /usr/bin/fuse-overlayfs: failed to mount ... Permission denied. This often points to FUSE configuration or permissions.
The actual mechanism that makes fuse-overlayfs efficient for rootless users is its ability to create isolated storage areas for each user. When running rootless, Podman uses a user’s home directory (e.g., ~/.local/share/containers/storage) for its storage. fuse-overlayfs then manages the overlay layers within this user-specific space, ensuring that one user cannot interfere with another’s containers or their underlying storage, all without requiring root privileges for the container process itself.
What most people don’t realize is that fuse-overlayfs has a mount_program option in storage.conf that allows you to specify the exact path to the fuse-overlayfs executable. If this is misconfigured or the executable isn’t in a standard location, Podman won’t be able to mount the container’s filesystem, leading to creation failures or errors during podman run. The default is usually /usr/bin/fuse-overlayfs, but on some systems or custom installations, it might be elsewhere.
The next logical step after understanding and configuring your storage driver is exploring how Podman manages image layers and how to optimize storage usage, perhaps by cleaning up unused images and containers.