Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

Btrfsmaintenance

github.com

  • Free plan
  • Open source
  • Linux
  • Self-hosted
7.4 Club score Visit github.com

What Btrfsmaintenance is

Btrfsmaintenance is a set of scripts for automating upkeep of btrfs filesystems on Linux or self-hosted systems. It handles scrub, balance, trim, and defragmentation, and each task can be enabled, disabled, and configured independently. Scrub reads filesystem data and metadata to check checksums; when redundant data or metadata includes a good copy, it can repair damaged data. Periodic tasks can run through cron or systemd timers, though a system uses only one scheduling method at a time. The project supports widely used distributions, provides installation guidance for Debian-based systems, and describes manual installation for other systems. On SUSE-based distributions, a zypper plugin can defragment RPM database files after package installation. Settings are designed for a default installation with btrfs on the root filesystem and can be adjusted in the sysconfig file. Scrub can generate intense reads, while balance can create significant read and write activity; serializing task concurrency can help limit resource use or task interactions. The project is licensed under GPL-2.0.

Who it suits

Btrfsmaintenance suits Linux administrators who want scheduled, configurable maintenance for btrfs filesystems. It may be useful to people who need to manage scrub, balance, trim, and defragmentation tasks.

Good to know, and what to watch

  • Maintenance tasks can be configured independently.
  • Scrub can repair data when a good redundant copy exists.
  • Supports cron or systemd timer scheduling.
  • A SUSE zypper plugin can defragment RPM database files.
  • Only one scheduling method can be active per system.
  • Scrub can cause intense reads.
  • Balance can create significant read and write activity.
  • Defragmentation does not descend into nested subvolumes or snapshots.

Btrfsmaintenance

Free

Free plan

The verdict

Btrfsmaintenance offers configurable scripts for common btrfs upkeep, with scheduling through cron or systemd timers. Plan for the read and write load of scrub and balance, and account for nested subvolumes or snapshots separately when configuring defragmentation.

What the maker publishes

API and SDK
The repository documents shell scripts, systemd units, configuration files and a Python or shell zypper plugin; it does not document a network API or SDK. source
Arch availability
Arch packages btrfsmaintenance 0.5.2-3 for the any architecture in its Extra repository and lists btrfs-progs as its dependency. source
Balancing
Its balance task reclaims underused Btrfs chunks using usage filters and can help avoid allocation problems caused by fragmented chunk space. source
Concurrency control
The BTRFS_ALLOW_CONCURRENCY setting can serialize maintenance jobs to reduce resource contention and task interaction. source
Configuration
Configuration values are designed for a default installation with btrfs on the root filesystem and can be adjusted in the documented sysconfig file. source
Configuration paths
SUSE and Red Hat derivatives use /etc/sysconfig/btrfsmaintenance, while Debian derivatives use /etc/default/btrfsmaintenance. source
Defragmentation
Its defrag task processes configured directories, while a separate zypper plugin defragments RPM database files after package transactions. source
Defragmentation limit
Configured directory defragmentation does not descend into other mount points, nested subvolumes, or snapshots; those paths must be listed separately. source
Dependencies
Debian packages depend on btrfs-progs and use either systemd or cron for scheduling. source
Distribution support
The project says it supports widely used distributions, provides installation guidance for Debian based systems, and describes manual installation for other systems. source
Documentation depth
The project README covers task behavior, tuning, scheduling, installation, distribution paths and snapshot-retention considerations, and release 0.5.1 added a manual page. source
Fedora availability
Fedora lists btrfsmaintenance versions for Rawhide and Fedora 43 through 45, with maintainers ngompa and atim. source
Gentoo availability
Gentoo offers version 0.5.2 and provides a systemd USE flag that selects systemd services and timers instead of cron timers. source
Independent adoption
Botmonster Tech gives installation examples for Debian/Ubuntu and Fedora and shows configuration for the package's systemd timers. source
Independent task configuration
Scrub, balance, trim and defrag can each be enabled, disabled and configured independently through the project configuration. source
Installation
Debian-based systems can use dist-install.sh, while other distributions can use distribution packages or manually install the scripts and service files. source
Integrations
A zypper plugin can defragment RPM database files after package installation on SUSE based distributions. source
Intended audience
The project describes its goal as helping administer btrfs filesystems and says common scripts and configurations are preferred over distribution specific ones. source
Latest documented release
The changelog identifies version 0.5.2 dated 2024-07-04 and records fixes for task startup syntax and sequential RAID5/RAID6 scrubbing. source
Licence
The repository is published under GPL-2.0, and Fedora identifies it as GPL-2.0-or-later. source
License
The repository identifies the project as licensed under GPL-2.0. source
Limit: balance workload
The documentation says balance can have a large read/write impact, needs workspace and may fail with a no-space reason requiring manual inspection. source
Limit: defrag and snapshots
An Unraid community discussion cautions that broad defragmentation can break copy-on-write deduplication and should generally be targeted, especially when snapshots are used. source
Limit: older kernel quota performance
The Ubuntu manpage warns that before kernel 5.2, balancing with quota groups enabled could stall the filesystem for an extended period. source

Checked against the maker's pages on 19 Oct 2026.