{ "mode": "man", "parameter": "btrfs-subvolume", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/btrfs-subvolume/8/json", "generated": "2026-06-14T00:49:59Z", "synopsis": "btrfs subvolume []", "sections": { "NAME": { "content": "btrfs-subvolume - manage btrfs subvolumes\n", "subsections": [] }, "SYNOPSIS": { "content": "btrfs subvolume []\n", "subsections": [] }, "DESCRIPTION": { "content": "btrfs subvolume is used to create/delete/list/show btrfs subvolumes and snapshots.\n", "subsections": [] }, "SUBVOLUME AND SNAPSHOT": { "content": "A subvolume is a part of filesystem with its own independent file/directory hierarchy.\nSubvolumes can share file extents. A snapshot is also subvolume, but with a given initial\ncontent of the original subvolume.\n\nNote\nA subvolume in btrfs is not like an LVM logical volume, which is block-level snapshot\nwhile btrfs subvolumes are file extent-based.\n\nA subvolume looks like a normal directory, with some additional operations described below.\nSubvolumes can be renamed or moved, nesting subvolumes is not restricted but has some\nimplications regarding snapshotting.\n\nA subvolume in btrfs can be accessed in two ways:\n\n• like any other directory that is accessible to the user\n\n• like a separately mounted filesystem (options subvol or subvolid)\n\nIn the latter case the parent directory is not visible and accessible. This is similar to a\nbind mount, and in fact the subvolume mount does exactly that.\n\nA freshly created filesystem is also a subvolume, called top-level, internally has an id 5.\nThis subvolume cannot be removed or replaced by another subvolume. This is also the subvolume\nthat will be mounted by default, unless the default subvolume has been changed (see\nsubcommand set-default).\n\nA snapshot is a subvolume like any other, with given initial content. By default, snapshots\nare created read-write. File modifications in a snapshot do not affect the files in the\noriginal subvolume.\n", "subsections": [] }, "SUBCOMMAND": { "content": "create [-i ] [/]\nCreate a subvolume in .\n\nIf is not given, subvolume will be created in the current directory.\n\nOptions\n\n-i \nAdd the newly created subvolume to a qgroup. This option can be given multiple times.\n\ndelete [options] <[ [...]], delete -i|--subvolid >\nDelete the subvolume(s) from the filesystem.\n\nIf is not a subvolume, btrfs returns an error but continues if there are more\narguments to process.\n\nIf --subvolid is used, must point to a btrfs filesystem. See btrfs subvolume list\nor btrfs inspect-internal rootid how to get the subvolume id.\n\nThe corresponding directory is removed instantly but the data blocks are removed later in\nthe background. The command returns immediately. See btrfs subvolume sync how to wait\nuntil the subvolume gets completely removed.\n\nThe deletion does not involve full transaction commit by default due to performance\nreasons. As a consequence, the subvolume may appear again after a crash. Use one of the\n--commit options to wait until the operation is safely stored on the device.\n\nThe default subvolume (see btrfs subvolume set-default) cannot be deleted and returns\nerror (EPERM) and this is logged to the system log. A subvolume that’s currently involved\nin send (see btrfs send) also cannot be deleted until the send is finished. This is also\nlogged in the system log.\n\nOptions\n\n-c|--commit-after\nwait for transaction commit at the end of the operation.\n\n-C|--commit-each\nwait for transaction commit after deleting each subvolume.\n\n-i|--subvolid \nsubvolume id to be removed instead of the that should point to the filesystem\nwith the subvolume\n\n-v|--verbose\n(deprecated) alias for global -v option\n\nfind-new \nList the recently modified files in a subvolume, after generation.\n\nget-default \nGet the default subvolume of the filesystem .\n\nThe output format is similar to subvolume list command.\n\nlist [options] [-G [+|-]] [-C [+|-]] [--sort=rootid,gen,ogen,path] \nList the subvolumes present in the filesystem .\n\nFor every subvolume the following information is shown by default:\n\nID gen top level path \n\nwhere ID is subvolume’s id, gen is an internal counter which is updated every\ntransaction, top level is the same as parent subvolume’s id, and path is the relative\npath of the subvolume to the top level subvolume. The subvolume’s ID may be used by the\nsubvolume set-default command, or at mount time via the subvolid= option.\n\nOptions\n\nPath filtering\n\n-o\nprint only subvolumes below specified .\n\n-a\nprint all the subvolumes in the filesystem and distinguish between absolute and\nrelative path with respect to the given .\n\nField selection\n\n-p\nprint the parent ID (parent here means the subvolume which contains this\nsubvolume).\n\n-c\nprint the ogeneration of the subvolume, aliases: ogen or origin generation.\n\n-g\nprint the generation of the subvolume (default).\n\n-u\nprint the UUID of the subvolume.\n\n-q\nprint the parent UUID of the subvolume (parent here means subvolume of which this\nsubvolume is a snapshot).\n\n-R\nprint the UUID of the sent subvolume, where the subvolume is the result of a\nreceive operation.\n\nType filtering\n\n-s\nonly snapshot subvolumes in the filesystem will be listed.\n\n-r\nonly readonly subvolumes in the filesystem will be listed.\n\n-d\nlist deleted subvolumes that are not yet cleaned.\n\nOther\n\n-t\nprint the result as a table.\n\nSorting\nBy default the subvolumes will be sorted by subvolume ID ascending.\n\n-G [+|-]\nlist subvolumes in the filesystem that its generation is >=, ⟨ or = value. '+'\nmeans >= value, '-' means <= value, If there is neither '+' nor '-', it means =\nvalue.\n\n-C [+|-]\nlist subvolumes in the filesystem that its ogeneration is >=, <= or = value. The\nusage is the same to -G option.\n\n--sort=rootid,gen,ogen,path\nlist subvolumes in order by specified items. you can add '+' or '-' in front of\neach items, '+' means ascending, '-' means descending. The default is ascending.\n\nfor --sort you can combine some items together by ',', just like\n--sort=+ogen,-gen,path,rootid.\n\nset-default [| ]\nSet the default subvolume for the (mounted) filesystem.\n\nSet the default subvolume for the (mounted) filesystem at . This will hide the\ntop-level subvolume (i.e. the one mounted with subvol=/ or subvolid=5). Takes action on\nnext mount.\n\nThere are two ways how to specify the subvolume, by or by the path. The\nid can be obtained from btrfs subvolume list, btrfs subvolume show or btrfs\ninspect-internal rootid.\n\nshow [options] \nShow more information about a subvolume (UUIDs, generations, times, flags, related\nsnapshots).\n\n/mnt/btrfs/subvolume\nName: subvolume\nUUID: 5e076a14-4e42-254d-ac8e-55bebea982d1\nParent UUID: -\nReceived UUID: -\nCreation time: 2018-01-01 12:34:56 +0000\nSubvolume ID: 79\nGeneration: 2844\nGen at creation: 2844\nParent ID: 5\nTop level ID: 5\nFlags: -\nSnapshot(s):\n\nOptions\n\n-r|--rootid \nshow details about subvolume with root , looked up in \n\n-u|--uuid UUID\nshow details about subvolume with the given , looked up in \n\nsnapshot [-r] [-i ] |[/]\nCreate a snapshot of the subvolume with the name in the directory.\n\nIf only is given, the subvolume will be named the basename of . If\n is not a subvolume, btrfs returns an error.\n\nOptions\n\n-r\nMake the new snapshot read only.\n\n-i \nAdd the newly created subvolume to a qgroup. This option can be given multiple times.\n\nsync [subvolid...]\nWait until given subvolume(s) are completely removed from the filesystem after deletion.\nIf no subvolume id is given, wait until all current deletion requests are completed, but\ndo not wait for subvolumes deleted in the meantime.\n\nOptions\n\n-s \nsleep N seconds between checks (default: 1)\n", "subsections": [] }, "SUBVOLUME FLAGS": { "content": "The subvolume flag currently implemented is the ro property. Read-write subvolumes have that\nset to false, snapshots as true. In addition to that, a plain snapshot will also have last\nchange generation and creation generation equal.\n\nRead-only snapshots are building blocks fo incremental send (see btrfs-send(8)) and the whole\nuse case relies on unmodified snapshots where the relative changes are generated from. Thus,\nchanging the subvolume flags from read-only to read-write will break the assumptions and may\nlead to unexpected changes in the resulting incremental stream.\n\nA snapshot that was created by send/receive will be read-only, with different last change\ngeneration, read-only and with set receiveduuid which identifies the subvolume on the\nfilesystem that produced the stream. The usecase relies on matching data on both sides.\nChanging the subvolume to read-write after it has been received requires to reset the\nreceiveduuid. As this is a notable change and could potentially break the incremental send\nuse case, performing it by btrfs property set requires force if that is really desired by\nuser.\n\nNote\nThe safety checks have been implemented in 5.14.2, any subvolumes previously received\n(with a valid receiveduuid) and read-write status may exist and could still lead to\nproblems with send/receive. You can use btrfs subvolume show to identify them. Flipping\nthe flags to read-only and back to read-write will reset the receiveduuid manually.\nThere may exist a convenience tool in the future.\n", "subsections": [] }, "EXAMPLES": { "content": "", "subsections": [ { "name": "Example 1. Deleting a subvolume", "content": "If we want to delete a subvolume called foo from a btrfs volume mounted at /mnt/bar we could\nrun the following:\n\nbtrfs subvolume delete /mnt/bar/foo\n" } ] }, "EXIT STATUS": { "content": "btrfs subvolume returns a zero exit status if it succeeds. A non-zero value is returned in\ncase of failure.\n", "subsections": [] }, "AVAILABILITY": { "content": "btrfs is part of btrfs-progs. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for\nfurther details.\n", "subsections": [] }, "SEE ALSO": { "content": "mkfs.btrfs(8), mount(8), btrfs-quota(8), btrfs-qgroup(8), btrfs-send(8)\n\n\n\nBtrfs v5.16.2 02/16/2022 BTRFS-SUBVOLUME(8)", "subsections": [] } }, "summary": "btrfs-subvolume - manage btrfs subvolumes", "flags": [], "examples": [ "If we want to delete a subvolume called foo from a btrfs volume mounted at /mnt/bar we could", "run the following:", "btrfs subvolume delete /mnt/bar/foo" ], "see_also": [ { "name": "mkfs.btrfs", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mkfs.btrfs/8/json" }, { "name": "mount", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mount/8/json" }, { "name": "btrfs-quota", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/btrfs-quota/8/json" }, { "name": "btrfs-qgroup", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/btrfs-qgroup/8/json" }, { "name": "btrfs-send", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/btrfs-send/8/json" }, { "name": "BTRFS-SUBVOLUME", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/BTRFS-SUBVOLUME/8/json" } ] }