compsize

Calculate the current compression ratio for a file or directory

$ sudo compsize [path/to/file_or_directory]

$ sudo compsize [[-x|--one-file-system]] [path/to/file_or_directory]

$ sudo compsize [[-b|--bytes]] [path/to/file_or_directory]

compsize [options] ...

-b, --bytes
    Show sizes in bytes rather than human-readable format (e.g., KB, MB, GB).


-x, --exclude
    Exclude files matching the specified glob .


-v, --verbose
    Print more detailed information during processing, often showing each file being processed.


-h, --help
    Display a help message and exit.


-V, --version
    Display version information and exit.


-r, --recursive
    Process directories recursively, descending into subdirectories.


-L, --dereference
    Dereference symbolic links. If a symbolic link points to a file or directory, the target of the link is processed instead of the link itself.


-p, --progress
    Display a progress bar during processing, useful for large operations.


-s, --summarize
    For directories, only show the total summary for logical, compressed sizes, and ratio, without listing individual files within.


-o, --output
    Write output to the specified instead of standard output.


-i, --include
    Include files matching the specified glob . This option can be used multiple times.


-n, --nthreads
    Specify the number of parallel threads to use for scanning.


-M, --min-size
    Only process files larger than the specified . Size can be suffixed with K, M, G, T, P, E.


-X, --max-size
    Only process files smaller than the specified . Size can be suffixed with K, M, G, T, P, E.

compsize is a specialized utility for the Btrfs filesystem, designed to analyze and report on the compression effectiveness of files and directories. It provides insights into the 'logical' size (the uncompressed data size) versus the 'compressed' size (the actual disk space consumed after Btrfs compression). By comparing these two values, compsize calculates and displays the compression ratio, which is crucial for understanding how much storage space is being saved by Btrfs's transparent compression features. This tool is invaluable for administrators and users who want to optimize storage usage, identify files that compress well or poorly, and fine-tune their Btrfs compression policies.

It can operate on individual files or recursively traverse directories, providing detailed statistics for each item and often a summary for directories. Unlike general-purpose disk usage tools like du, compsize specifically understands and reports on Btrfs's compression mechanisms.

compsize is a Btrfs-specific utility and will only provide meaningful output for files located on a Btrfs filesystem. It requires appropriate permissions to read the files and their metadata, typically needing root privileges or CAP_SYS_ADMIN capabilities if accessing underlying block devices directly, though standard file permissions suffice for mounted filesystems. It does not modify files; it only reports on their compression status.

The default output of compsize typically presents information in columns:
1. Logical Size: The uncompressed size of the data.
2. Compressed Size: The actual size the data occupies on disk after Btrfs compression.
3. Ratio: The compression ratio (Logical Size / Compressed Size). A ratio greater than 1.0 indicates effective compression.
4. Path: The full path to the file or directory being analyzed.

To check compression for a single file:
compsize /path/to/your/file.txt

To recursively check an entire directory and get a summarized total for it:
compsize -r -s /path/to/your/directory/

To see verbose output while processing files in a directory:
compsize -rv /path/to/another/directory/

compsize is part of the btrfs-progs package, the official userspace utilities for managing the Btrfs filesystem. It was developed alongside the Btrfs filesystem itself to provide administrators with tools to understand and optimize its unique features, such as transparent compression. Its functionality has evolved to include various filtering and reporting options, reflecting the growing adoption and need for deeper insights into Btrfs's performance and storage characteristics.

btrfs(8), du(1), ls(1), stat(1)