btrfs-gui is a graphical user interface tool for inspecting and managing btrfs filesystems. It is capable of managing filesystems on the local machine, and filesystems on remote network-accessible machines. It requires root access to the machine to perform most of its tasks (but separates the root-access part from the GUI).

Development status

Development is in its early stages, and currently only disk usage information and a list of subvolumes is available.


  • python 3.1 or later for the GUI part of the tool
  • tkinter.ttk (often packaged as python-tk)
  • python 2.6 or later for the root-level helper
  • A recent kernel supporting btrfs

If you only have python 3, you should be able to run the root-level helper after patching it with the 2to3 tool. When there's a "make install", this capability will be in-built.

Getting btrfs-gui

btrfs-gui is currently available through its git repository:

$ git clone

The repository can also be viewed through gitweb.

Note that the first time you download the git repository, you will need to run make to generate the icons the GUI needs. This requires inkscape and imagemagick. If you do not have these, the makefile will download the icons from this site instead. The icon files are also shipped in the tarball distribution of btrfs-gui (see below).

You can also download tarballs of the latest releases and release candidates.


$ sudo python3 install

Using the GUI

Run it with:

$ sudo btrfs-gui

The GUI will appear. (Note that although the GUI is started through sudo, the main part of the program immediately drops root privileges again: only a small helper app is actually run as root). Select "scan for filesystems" from the Filesystems menu, and a list of btrfs filesystems will be shown in the panel on the left-hand side. The underlying devices for each filesystem are also shown in the list. Double-click on a filesystem to select it.

The usage display

Usage display

The usage display shows, graphically, what space has been allocated and used. The topmost box by default shows only what has been allocated by the filesystem -- this may be only a fraction of the total space available. Where data is replicated (RAID-1, RAID-10 or DUP), only the size of the actual data is shown, not the total of all copies of it. (i.e. 10GiB of RAID-1 data is shown as 10GiB, not as 20GiB). The boxes underneath show the disk space used on each of the devices underlying the filesystem.

The striped sections show allocated but unused space; the black section at the beginning of each block is the system data.

The subvolume display

Subvolume display

The subvolume display lists all of the subvolumes of the filesystem. Subvolumes can be created from the "Subvolumes → New" menu, and deleted by selecting a subvolume in the list and using "Subvolumes → Delete", or right-clicking to bring up a context menu, and selecting "Delete".

is project alive?

Hi, is that project alive? I'm running in JSON problems with Ubuntu 12.04:

Helper: found label None, UUID 8230eaa2-3969-4b1e-9ce0-047cee13bf39
Helper: found dev 1 = /dev/sda2
Helper: Created private directory /tmp/btrfs-gui-cd93i7
Helper: Mounted filesystem UUID=8230eaa2-3969-4b1e-9ce0-047cee13bf39 at /tmp/btrfs-gui-cd93i7/20820/8230eaa2-3969-4b1e-9ce0-047cee13bf39
Traceback (most recent call last):
File "/usr/local/lib/python3.2/dist-packages/btrfsgui/hlp/", line 40, in main
File "/usr/local/lib/python3.2/dist-packages/btrfsgui/hlp/", line 126, in sv_list
File "/usr/lib/python3.2/json/", line 226, in dumps
return _default_encoder.encode(obj)
File "/usr/lib/python3.2/json/", line 188, in encode
chunks = self.iterencode(o, _one_shot=True)
File "/usr/lib/python3.2/json/", line 246, in iterencode
return _iterencode(o, 0)
File "/usr/lib/python3.2/json/", line 170, in default
raise TypeError(repr(o) + " is not JSON serializable")
TypeError: b'test' is not JSON serializable

It's not definitively dead,

It's not definitively dead, at least. I'll see if I've got a bit of time to look at this issue over the Christmas break. Mailing the btrfs mailing list with this might have got a faster response, though. (I don't read comments very often, due to the quantitiy of spam I have to delete every time I do it).