In this lesson, you will learn how to distinguish between the various ways Btrfs measures your storage usage so you don’t panic when your "disk full" reports don't match your file sizes.
The Three Layers of Btrfs Space
When you look at Btrfs, you are dealing with a "copy-on-write" filesystem that separates the user’s view from the physical reality. To understand your disk usage, you must look at three distinct numbers:
1. Logical Size
This is the "apparent" size of your files—what you see when you run ls -lh. If you have a 1GB text file, the logical size is 1GB. However, due to features like snapshots, reflinks, or compression, this number rarely matches the actual space consumed on your drive.
2. Physical Usage
This is the amount of disk space actually occupied by data blocks. If you use compression (like zstd), Btrfs stores the compressed version on the physical medium. If you write 1GB of data, but the compression engine shrinks it to 600MB, your Physical Usage is 600MB, while your Logical Size remains 1GB.
3. Effective Space
Because Btrfs uses Copy-on-Write (CoW), a single file might share blocks with a snapshot. If you have two 1GB files that are identical copies (reflinks), the Logical Size shows 2GB, but the Physical Usage might be only 1GB because they point to the same physical blocks.
Viewing the Nuances
The standard df command can be misleading because it doesn't account for Btrfs’s internal chunk allocation or compression. To see the true accounting, use the Btrfs-specific tool:
# See how much space is actually being used by data vs metadata
sudo btrfs filesystem usage /mountpoint
In the output, look for the "Device size" (total allocation) versus "Data, single" (actual physical data stored). If you see "Global Reserve," keep in mind that Btrfs sets aside this space for critical operations to prevent filesystem corruption during out-of-memory or out-of-space events—this is physical space you cannot use for your own files.
Key Takeaway: Because of compression and CoW, your file sizes (logical) and disk usage (physical) will rarely align; always use btrfs filesystem usage to see the actual footprint on your hardware.