{
    "mode": "info",
    "parameter": "BTRFS-QUOTA",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/BTRFS-QUOTA/json",
    "generated": "2026-07-05T15:55:28Z",
    "synopsis": "btrfs quota <subcommand> <args>",
    "sections": {
        "NAME": {
            "content": "btrfs-quota - control the global quota status of a btrfs filesystem\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "btrfs quota <subcommand> <args>\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The commands under btrfs quota are used to affect the global status of\nquotas of a btrfs filesystem. The quota groups (qgroups) are managed by\nthe subcommand btrfs qgroup(8).\n\nNote\nQgroups are different than the traditional user quotas and designed\nto track shared and exclusive data per-subvolume. Please refer to\nthe section HIERARCHICAL QUOTA GROUP CONCEPTS for a detailed\ndescription.\n\nPERFORMANCE IMPLICATIONS\nWhen quotas are activated, they affect all extent processing, which\ntakes a performance hit. Activation of qgroups is not recommended\nunless the user intends to actually use them.\n\nSTABILITY STATUS\nThe qgroup implementation has turned out to be quite difficult as it\naffects the core of the filesystem operation. Qgroup users have hit\nvarious corner cases over time, such as incorrect accounting or system\ninstability. The situation is gradually improving and issues found and\nfixed.\n",
            "subsections": []
        },
        "HIERARCHICAL QUOTA GROUP CONCEPTS": {
            "content": "The concept of quota has a long-standing tradition in the Unix world.\nEver since computers allow multiple users to work simultaneously in one\nfilesystem, there is the need to prevent one user from using up the\nentire space. Every user should get his fair share of the available\nresources.\n\nIn case of files, the solution is quite straightforward. Each file has\nan owner recorded along with it, and it has a size. Traditional quota\njust restricts the total size of all files that are owned by a user.\nThe concept is quite flexible: if a user hits his quota limit, the\nadministrator can raise it on the fly.\n\nOn the other hand, the traditional approach has only a poor solution to\nrestrict directories. At installation time, the harddisk can be\npartitioned so that every directory (eg. /usr, /var/, ...) that needs a\nlimit gets its own partition. The obvious problem is that those limits\ncannot be changed without a reinstallation. The btrfs subvolume feature\nbuilds a bridge. Subvolumes correspond in many ways to partitions, as\nevery subvolume looks like its own filesystem. With subvolume quota, it\nis now possible to restrict each subvolume like a partition, but keep\nthe flexibility of quota. The space for each subvolume can be expanded\nor restricted on the fly.\n\nAs subvolumes are the basis for snapshots, interesting questions arise\nas to how to account used space in the presence of snapshots. If you\nhave a file shared between a subvolume and a snapshot, whom to account\nthe file to? The creator? Both? What if the file gets modified in the\nsnapshot, should only these changes be accounted to it? But wait, both\nthe snapshot and the subvolume belong to the same user home. I just\nwant to limit the total space used by both! But somebody else might not\nwant to charge the snapshots to the users.\n\nBtrfs subvolume quota solves these problems by introducing groups of\nsubvolumes and let the user put limits on them. It is even possible to\nhave groups of groups. In the following, we refer to them as qgroups.\n\nEach qgroup primarily tracks two numbers, the amount of total\nreferenced space and the amount of exclusively referenced space.\n\nreferenced\nspace is the amount of data that can be reached from any of the\nsubvolumes contained in the qgroup, while\n\nexclusive\nis the amount of data where all references to this data can be\nreached from within this qgroup.\n\nSUBVOLUME QUOTA GROUPS\nThe basic notion of the Subvolume Quota feature is the quota group,\nshort qgroup. Qgroups are notated as level/id, eg. the qgroup 3/2 is a\nqgroup of level 3. For level 0, the leading 0/ can be omitted. Qgroups\nof level 0 get created automatically when a subvolume/snapshot gets\ncreated. The ID of the qgroup corresponds to the ID of the subvolume,\nso 0/5 is the qgroup for the root subvolume. For the btrfs qgroup\ncommand, the path to the subvolume can also be used instead of 0/ID.\nFor all higher levels, the ID can be chosen freely.\n\nEach qgroup can contain a set of lower level qgroups, thus creating a\nhierarchy of qgroups. Figure 1 shows an example qgroup tree.\n\n+---+\n|2/1|\n+---+\n/     \\\n+---+/       \\+---+\n|1/1|         |1/2|\n+---+         +---+\n/     \\       /     \\\n+---+/       \\+---+/       \\+---+\nqgroups     |0/1|         |0/2|         |0/3|\n+-+-+         +---+         +---+\n|          /     \\       /     \\\n|         /       \\     /       \\\n|        /         \\   /         \\\nextents       1       2            3            4\n\nFigure1: Sample qgroup hierarchy\n\nAt the bottom, some extents are depicted showing which qgroups\nreference which extents. It is important to understand the notion of\nreferenced vs exclusive. In the example, qgroup 0/2 references extents\n2 and 3, while 1/2 references extents 2-4, 2/1 references all extents.\n\nOn the other hand, extent 1 is exclusive to 0/1, extent 2 is exclusive\nto 0/2, while extent 3 is neither exclusive to 0/2 nor to 0/3. But\nbecause both references can be reached from 1/2, extent 3 is exclusive\nto 1/2. All extents are exclusive to 2/1.\n\nSo exclusive does not mean there is no other way to reach the extent,\nbut it does mean that if you delete all subvolumes contained in a\nqgroup, the extent will get deleted.\n\nExclusive of a qgroup conveys the useful information how much space\nwill be freed in case all subvolumes of the qgroup get deleted.\n\nAll data extents are accounted this way. Metadata that belongs to a\nspecific subvolume (i.e. its filesystem tree) is also accounted.\nChecksums and extent allocation information are not accounted.\n\nIn turn, the referenced count of a qgroup can be limited. All writes\nbeyond this limit will lead to a Quota Exceeded error.\n\nINHERITANCE\nThings get a bit more complicated when new subvolumes or snapshots are\ncreated. The case of (empty) subvolumes is still quite easy. If a\nsubvolume should be part of a qgroup, it has to be added to the qgroup\nat creation time. To add it at a later time, it would be necessary to\nat least rescan the full subvolume for a proper accounting.\n\nCreation of a snapshot is the hard case. Obviously, the snapshot will\nreference the exact amount of space as its source, and both source and\ndestination now have an exclusive count of 0 (the filesystem nodesize\nto be precise, as the roots of the trees are not shared). But what\nabout qgroups of higher levels? If the qgroup contains both the source\nand the destination, nothing changes. If the qgroup contains only the\nsource, it might lose some exclusive.\n\nBut how much? The tempting answer is, subtract all exclusive of the\nsource from the qgroup, but that is wrong, or at least not enough.\nThere could have been an extent that is referenced from the source and\nanother subvolume from that qgroup. This extent would have been\nexclusive to the qgroup, but not to the source subvolume. With the\ncreation of the snapshot, the qgroup would also lose this extent from\nits exclusive set.\n\nSo how can this problem be solved? In the instant the snapshot gets\ncreated, we already have to know the correct exclusive count. We need\nto have a second qgroup that contains all the subvolumes as the first\nqgroup, except the subvolume we want to snapshot. The moment we create\nthe snapshot, the exclusive count from the second qgroup needs to be\ncopied to the first qgroup, as it represents the correct value. The\nsecond qgroup is called a tracking qgroup. It is only there in case a\nsnapshot is needed.\n\nUSE CASES\nBelow are some usecases that do not mean to be extensive. You can find\nyour own way how to integrate qgroups.\n\nSINGLE-USER MACHINE\nReplacement for partitions\n\nThe simplest use case is to use qgroups as simple replacement for\npartitions. Btrfs takes the disk as a whole, and /, /usr, /var,\netc. are created as subvolumes. As each subvolume gets it own\nqgroup automatically, they can simply be restricted. No hierarchy\nis needed for that.\n\nTrack usage of snapshots\n\nWhen a snapshot is taken, a qgroup for it will automatically be\ncreated with the correct values. Referenced will show how much is\nin it, possibly shared with other subvolumes. Exclusive will be the\namount of space that gets freed when the subvolume is deleted.\n\nMULTI-USER MACHINE\nRestricting homes\n\nWhen you have several users on a machine, with home directories\nprobably under /home, you might want to restrict /home as a whole,\nwhile restricting every user to an individual limit as well. This\nis easily accomplished by creating a qgroup for /home , eg. 1/1,\nand assigning all user subvolumes to it. Restricting this qgroup\nwill limit /home, while every user subvolume can get its own\n(lower) limit.\n\nAccounting snapshots to the user\n\nLet's say the user is allowed to create snapshots via some\nmechanism. It would only be fair to account space used by the\nsnapshots to the user. This does not mean the user doubles his\nusage as soon as he takes a snapshot. Of course, files that are\npresent in his home and the snapshot should only be accounted once.\nThis can be accomplished by creating a qgroup for each user, say\n1/UID. The user home and all snapshots are assigned to this qgroup.\nLimiting it will extend the limit to all snapshots, counting files\nonly once. To limit /home as a whole, a higher level group 2/1\nreplacing 1/1 from the previous example is needed, with all user\nqgroups assigned to it.\n\nDo not account snapshots\n\nOn the other hand, when the snapshots get created automatically,\nthe user has no chance to control them, so the space used by them\nshould not be accounted to him. This is already the case when\ncreating snapshots in the example from the previous section.\n\nSnapshots for backup purposes\n\nThis scenario is a mixture of the previous two. The user can create\nsnapshots, but some snapshots for backup purposes are being created\nby the system. The user's snapshots should be accounted to the\nuser, not the system. The solution is similar to the one from\nsection Accounting snapshots to the user, but do not assign system\nsnapshots to user's qgroup.\n",
            "subsections": []
        },
        "SUBCOMMAND": {
            "content": "disable <path>\nDisable subvolume quota support for a filesystem.\n\nenable <path>\nEnable subvolume quota support for a filesystem.\n\nrescan [-s] <path>\nTrash all qgroup numbers and scan the metadata again with the\ncurrent config.\n\nOptions\n\n-s\nshow status of a running rescan operation.\n\n-w\nwait for rescan operation to finish(can be already in\nprogress).\n",
            "subsections": []
        },
        "EXIT STATUS": {
            "content": "btrfs quota returns a zero exit status if it succeeds. Non zero is\nreturned in case of failure.\n",
            "subsections": []
        },
        "AVAILABILITY": {
            "content": "btrfs is part of btrfs-progs. Please refer to the btrfs wiki\nhttp://btrfs.wiki.kernel.org for further details.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "mkfs.btrfs(8), btrfs-subvolume(8), btrfs-qgroup(8)\n\nBtrfs v5.16.2                     02/16/2022                    BTRFS-QUOTA(8)",
            "subsections": []
        }
    },
    "summary": "btrfs-quota - control the global quota status of a btrfs filesystem",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "mkfs.btrfs",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/mkfs.btrfs/8/json"
        },
        {
            "name": "btrfs-subvolume",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/btrfs-subvolume/8/json"
        },
        {
            "name": "btrfs-qgroup",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/btrfs-qgroup/8/json"
        }
    ]
}