Visualize the layout of data on your btrfs filesystem over time
Clone or download
knorrie Don't blow up when the target is not btrfs
This might also accidentally happen to the user.
Latest commit 4a7768e Sep 22, 2017
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Fix typo Mar 5, 2017
.gitignore Reorganize documentation files and pics Feb 9, 2017
COPYING Add license / copyright info Mar 5, 2017 README: housekeeping Sep 22, 2017 Don't blow up when the target is not btrfs Sep 22, 2017

Btrfs Heatmap

The btrfs heatmap script creates a visualization of how a btrfs filesystem is using the underlying disk space of the block devices that are added to it.

What does it look like?

238GiB file system

This picture shows the 238GiB filesystem in my computer at work. It was generated using the command ./ --size 9 /, resulting in a 512x512 pixel png. The black parts are unallocated disk space. Raw disk space that is allocated to be used for data (white), metadata (blue) or system (red) gets brighter if the fill factor of block groups is higher.

How do I create a picture like this of my own computer?

To run the program, you need to clone two git repositories:

The fastest way to get it running is:

-$ git clone
-$ git clone
-$ cd btrfs-heatmap
btrfs-heatmap (master) -$ ln -s ../python-btrfs/btrfs/
btrfs-heatmap (master) -$ sudo ./ /mountpoint

When pointing to a mounted btrfs filesystem location, it will ask the linux kernel for usage information and build a png picture reflecting that low level information.

Because the needed information is retrieved using the btrfs kernel API, it has to be run as root. If you don't trust it, don't run it on your system.

I have a picture now, with quite a long filename, why?

The filename of the png picture is a combination of the filesystem ID and a timestamp by default, so that if you create multiple of them, they nicely pile up as input for creating a timelapse video.

Creating multiple ones is as easy as doing watch './ /mountpoint'

Where's what? In what corner is the first or last byte located?

By default, the ordering inside the picture is based on a Hilbert Curve. The lowest physical address of the block devices is located in the bottom left corner. From there it walks up, to the right and down again.

Hilbert Curve Example Image
Hilbert Curve Mekker

In btrfs technical terms speaking, what does it display?

The picture that is generated by default shows the physical address space of a filesystem, by walking all dev extents of all devices in the filesystem using the search ioctl and concatenating all information into a single big image. The usage values are computed by looking up usage counters in the block group items from the extent tree.

It's also possible to have the picture sorted by btrfs virtual address space instead, or to create pictures of the contents of block groups, on extent level. For more information, see links to additional documentation below.

How do I create a timelapse movie out of this?

Here's an example command to create an mp4 video out of all the png files if you create multiple ones over time:

ffmpeg -framerate 2 -pattern_type glob -i '*.png' -c:v libx264 -r 25 -pix_fmt yuv420p btrfs-heatmap.mp4

By varying the -framerate option, you can make the video go faster or slower.

Another option is to create an animated gif. By varying the -delay option, you change the speed.

convert -layers optimize-frame -loop 0 -delay 20 *.png btrfs-heatmap.gif

The next picture is an animated gif of running btrfs balance on the data of the filesystem which the first picture was also taken of. You can see how all free space is defragmented by packing data together:

btrfs balance
animated gif balance

More documentation and advanced usage


Let me know if this program was useful for you, or if you have brilliant ideas about how to improve it.

You can reach me on IRC in #btrfs on Freenode (I'm Knorrie), use the github issue system or send me an email on