{ "mode": "man", "parameter": "BTRFS-FILESYSTEM", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/BTRFS-FILESYSTEM/8/json", "generated": "2026-10-05T14:58:15Z", "synopsis": "btrfs filesystem ", "sections": { "NAME": { "content": "btrfs-filesystem - command group that primarily does work on the whole filesystems\n", "subsections": [] }, "SYNOPSIS": { "content": "btrfs filesystem \n", "subsections": [] }, "DESCRIPTION": { "content": "btrfs filesystem is used to perform several whole filesystem level tasks, including all the\nregular filesystem operations like resizing, space stats, label setting/getting, and defrag‐\nmentation. There are other whole filesystem tasks like scrub or balance that are grouped in\nseparate commands.\n", "subsections": [] }, "SUBCOMMAND": { "content": "", "subsections": [ { "name": "df [options] ", "content": "Show a terse summary information about allocation of block group types of a given\nmount point. The original purpose of this command was a debugging helper. The output\nneeds to be further interpreted and is not suitable for quick overview.\n\nAn example with description:\n\n• device size: 1.9TiB, one device, no RAID\n\n• filesystem size: 1.9TiB\n\n• created with: mkfs.btrfs -d single -m single\n\n$ btrfs filesystem df /path\nData, single: total=1.15TiB, used=1.13TiB\nSystem, single: total=32.00MiB, used=144.00KiB\nMetadata, single: total=12.00GiB, used=6.45GiB\nGlobalReserve, single: total=512.00MiB, used=0.00B\n\n• Data, System and Metadata are separate block group types. GlobalReserve is an arti‐\nficial and internal emergency space, see below.\n\n• single -- the allocation profile, defined at mkfs time\n\n• total -- sum of space reserved for all allocation profiles of the given type, i.e.\nall Data/single. Note that it's not total size of filesystem.\n\n• used -- sum of used space of the above, i.e. file extents, metadata blocks\n\nGlobalReserve is an artificial and internal emergency space. It is used e.g. when the\nfilesystem is full. Its total size is dynamic based on the filesystem size, usually\nnot larger than 512MiB, used may fluctuate.\n\nThe GlobalReserve is a portion of Metadata. In case the filesystem metadata is ex‐\nhausted, GlobalReserve/total + Metadata/used = Metadata/total. Otherwise there appears\nto be some unused space of Metadata.\n\nOptions\n\n-b|--raw\nraw numbers in bytes, without the B suffix\n\n-h|--human-readable\nprint human friendly numbers, base 1024, this is the default\n\n-H print human friendly numbers, base 1000\n\n--iec select the 1024 base for the following options, according to the IEC standard\n\n--si select the 1000 base for the following options, according to the SI standard\n\n-k|--kbytes\nshow sizes in KiB, or kB with --si\n\n-m|--mbytes\nshow sizes in MiB, or MB with --si\n\n-g|--gbytes\nshow sizes in GiB, or GB with --si\n\n-t|--tbytes\nshow sizes in TiB, or TB with --si\n\nIf conflicting options are passed, the last one takes precedence.\n" }, { "name": "defragment [options] | [|...]", "content": "Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer.\n\nIf -r is passed, files in dir will be defragmented recursively (not descending to sub‐\nvolumes, mount points and directory symlinks). The start position and the number of\nbytes to defragment can be specified by start and length using -s and -l options be‐\nlow. Extents bigger than value given by -t will be skipped, otherwise this value is\nused as a target extent size, but is only advisory and may not be reached if the free\nspace is too fragmented. Use 0 to take the kernel default, which is 256KiB but may\nchange in the future. You can also turn on compression in defragment operations.\n\nWARNING:\nDefragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as with Linux\nstable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up the reflinks\nof COW data (for example files copied with cp --reflink, snapshots or de-duplicated\ndata). This may cause considerable increase of space usage depending on the broken\nup reflinks.\n\nNOTE:\nDirectory arguments without -r do not defragment files recursively but will defrag‐\nment certain internal trees (extent tree and the subvolume tree). This has been\nconfusing and could be removed in the future.\n\nFor start, len, size it is possible to append units designator: K, M, G, T, P, or E,\nwhich represent KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).\n\nOptions\n\n-c[]\ncompress file contents while defragmenting. Optional argument selects the com‐\npression algorithm, zlib (default), lzo or zstd. Currently it's not possible to\nselect no compression. See also section EXAMPLES.\n\n-r defragment files recursively in given directories, does not descend to subvol‐\numes or mount points\n\n-f flush data for each file before going to the next file.\n\nThis will limit the amount of dirty data to current file, otherwise the amount\naccumulates from several files and will increase system load. This can also\nlead to ENOSPC if there's too much dirty data to write and it's not possible to\nmake the reservations for the new data (i.e. how the COW design works).\n\n-s [kKmMgGtTpPeE]\ndefragmentation will start from the given offset, default is beginning of a\nfile\n\n-l [kKmMgGtTpPeE]\ndefragment only up to len bytes, default is the file size\n\n-t [kKmMgGtTpPeE]\ntarget extent size, do not touch extents bigger than size, default: 32MiB\n\nThe value is only advisory and the final size of the extents may differ, de‐\npending on the state of the free space and fragmentation or other internal\nlogic. Reasonable values are from tens to hundreds of megabytes.\n\n--step SIZE\nPerform defragmention in the range in SIZE steps and flush (-f) after each one.\nThe range is default (the whole file) or given by -s and -l, split into the\nsteps or done in one go if the step is larger. Minimum range size is 256KiB.\n" }, { "name": "-v (deprecated)", "content": "", "flag": "-v" }, { "name": "du [options] [..]", "content": "Calculate disk usage of the target files using FIEMAP. For individual files, it will\nreport a count of total bytes, and exclusive (not shared) bytes. We also calculate a\n'set shared' value which is described below.\n\nEach argument to btrfs filesystem du will have a set shared value calculated for it.\nWe define each set as those files found by a recursive search of an argument (recur‐\nsion descends to subvolumes but not mount points). The set shared value then is a sum\nof all shared space referenced by the set.\n\nset shared takes into account overlapping shared extents, hence it isn't as simple as\nadding up shared extents.\n\nOptions\n\n-s|--summarize\ndisplay only a total for each argument\n\n--raw raw numbers in bytes, without the B suffix.\n\n--human-readable\nprint human friendly numbers, base 1024, this is the default\n\n--iec select the 1024 base for the following options, according to the IEC standard.\n\n--si select the 1000 base for the following options, according to the SI standard.\n\n--kbytes\nshow sizes in KiB, or kB with --si.\n\n--mbytes\nshow sizes in MiB, or MB with --si.\n\n--gbytes\nshow sizes in GiB, or GB with --si.\n\n--tbytes\nshow sizes in TiB, or TB with --si.\n" }, { "name": "label [|] []", "content": "Show or update the label of a filesystem. This works on a mounted filesystem or a\nfilesystem image.\n\nThe newlabel argument is optional. Current label is printed if the argument is omit‐\nted.\n\nNOTE:\nThe maximum allowable length shall be less than 256 chars and must not contain a\nnewline. The trailing newline is stripped automatically.\n" }, { "name": "mkswapfile [-s size] file", "content": "Create a new file that's suitable and formatted as a swapfile. Default size is 2GiB,\nfixed page size 4KiB, minimum size is 40KiB.\n\nA swapfile must be created in a specific way: NOCOW and preallocated. Subvolume con‐\ntaining a swapfile cannot be snapshotted and blocks of an activated swapfile cannot be\nbalanced.\n\nSwapfile creation can be achieved by standalone commands too. Activation needs to be\ndone by command swapon(8). See also command btrfs inspect-internal map-swapfile and\nthe Swapfile feature description.\n\nNOTE:\nThe command is a simplified version of 'mkswap', if you want to set label, page\nsize, or other parameters please use 'mkswap' proper.\n\nOptions\n\n-s|--size SIZE\nCreate swapfile of a given size SIZE (accepting k/m/g/e/p suffix).\n\n-U|--uuid UUID\nspecify UUID to use, or a special value: clear (all zeros), random, time\n(time-based random)\n" }, { "name": "resize [options] [:][+/-][kKmMgGtTpPeE]|[:]max ", "content": "Resize a mounted filesystem identified by path. A particular device can be resized by\nspecifying a devid.\n\nWARNING:\nIf path is a file containing a BTRFS image then resize does not work as expected\nand does not resize the image. This would resize the underlying filesystem instead.\n\nThe devid can be found in the output of btrfs filesystem show and defaults to 1 if not\nspecified. The size parameter specifies the new size of the filesystem. If the pre‐\nfix + or - is present the size is increased or decreased by the quantity size. If no\nunits are specified, bytes are assumed for size. Optionally, the size parameter may\nbe suffixed by one of the following unit designators: K, M, G, T, P, or E, which rep‐\nresent KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).\n\nIf max is passed, the filesystem will occupy all available space on the device re‐\nspecting devid (remember, devid 1 by default).\n\nThe resize command does not manipulate the size of underlying partition. If you wish\nto enlarge/reduce a filesystem, you must make sure you can expand the partition before\nenlarging the filesystem and shrink the partition after reducing the size of the\nfilesystem. This can done using fdisk(8) or parted(8) to delete the existing parti‐\ntion and recreate it with the new desired size. When recreating the partition make\nsure to use the same starting partition offset as before.\n\nGrowing is usually instant as it only updates the size. However, shrinking could take\na long time if there are data in the device area that's beyond the new end. Relocation\nof the data takes time.\n\nSee also section EXAMPLES.\n\nOptions\n\n--enqueue\nwait if there's another exclusive operation running, otherwise continue\n" }, { "name": "show [options] [|||