1MKFS.BTRFS(8) BTRFS MKFS.BTRFS(8)
2
6 mkfs.btrfs - create a btrfs filesystem
7
9 mkfs.btrfs [options] <device> [<device>...]
10
12 mkfs.btrfs is used to create the btrfs filesystem on a single or multi‐
13 ple devices. The device is typically a block device but can be a
14 file-backed image as well. Multiple devices are grouped by UUID of the
15 filesystem.
16 Before mounting such filesystem, the kernel module must know all the
18 devices either via preceding execution of btrfs device scan or using
19 the device mount option. See section MULTIPLE DEVICES for more details.
20 The default block group profiles for data and metadata depend on number
22 of devices and possibly other factors. It's recommended to use specific
23 profiles but the defaults should be OK and allowing future conversions
24 to other profiles. Please see options -d and -m for further details
25 and btrfs-balance(8) for the profile conversion post mkfs.
26
28 -b|--byte-count <size>
29 Specify the size of each device as seen by the filesystem. If
30 not set, the entire device size is used. The total filesystem
31 size will be sum of all device sizes, for a single device
32 filesystem the option effectively specifies the size of the
33 filesystem.
34 --csum <type>, --checksum <type>
36 Specify the checksum algorithm. Default is crc32c. Valid values
37 are crc32c, xxhash, sha256 or blake2. To mount such filesystem
38 kernel must support the checksums as well. See section CHECKSUM
39 ALGORITHMS in btrfs(5).
40 -d|--data <profile>
42 Specify the profile for the data block groups. Valid values are
43 raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10 or single
44 or dup (case does not matter).
45 See section DUP PROFILES ON A SINGLE DEVICE for more details.
47 On multiple devices, the default was raid0 until version 5.7,
49 while it is single since version 5.8. You can still select raid0
50 manually, but it was not suitable as default.
51 -m|--metadata <profile>
53 Specify the profile for the metadata block groups. Valid values
54 are raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10, single
55 or dup (case does not matter).
56 Default on a single device filesystem is DUP and is recommended
58 for metadata in general. The duplication might not be necessary
59 in some use cases and it's up to the user to changed that at
60 mkfs time or later. This depends on hardware that could poten‐
61 tially deduplicate the blocks again but this cannot be detected
62 at mkfs time.
63 NOTE:
65 Up to version 5.14 there was a detection of a SSD device
66 (more precisely if it's a rotational device, determined by
67 the contents of file /sys/block/DEV/queue/rotational) that
68 used to select single. This has changed in version 5.15 to be
69 always dup.
70 Note that the rotational status can be arbitrarily set by the
72 underlying block device driver and may not reflect the true
73 status (network block device, memory-backed SCSI devices,
74 real block device behind some additional device mapper layer,
75 etc). It's recommended to always set the options
76 --data/--metadata to avoid confusion and unexpected results.
77 See section DUP PROFILES ON A SINGLE DEVICE for more details.
79 On multiple devices the default is raid1.
81 -M|--mixed
83 Normally the data and metadata block groups are isolated. The
84 mixed mode will remove the isolation and store both types in the
85 same block group type. This helps to utilize the free space re‐
86 gardless of the purpose and is suitable for small devices. The
87 separate allocation of block groups leads to a situation where
88 the space is reserved for the other block group type, is not
89 available for allocation and can lead to ENOSPC state.
90 The recommended size for the mixed mode is for filesystems less
92 than 1GiB. The soft recommendation is to use it for filesystems
93 smaller than 5GiB. The mixed mode may lead to degraded perfor‐
94 mance on larger filesystems, but is otherwise usable, even on
95 multiple devices.
96 The nodesize and sectorsize must be equal, and the block group
98 types must match.
99 NOTE:
101 Versions up to 4.2.x forced the mixed mode for devices
102 smaller than 1GiB. This has been removed in 4.3+ as it
103 caused some usability issues.
104 Mixed profile cannot be used together with other profiles. It
106 can only be set at creation time. Conversion to or from mixed
107 profile is not implemented.
108 -n|--nodesize <size>
110 Specify the nodesize, the tree block size in which btrfs stores
111 metadata. The default value is 16KiB (16384) or the page size,
112 whichever is bigger. Must be a multiple of the sectorsize and a
113 power of 2, but not larger than 64KiB (65536). Leafsize always
114 equals nodesize and the options are aliases.
115 Smaller node size increases fragmentation but leads to taller
117 b-trees which in turn leads to lower locking contention. Higher
118 node sizes give better packing and less fragmentation at the
119 cost of more expensive memory operations while updating the
120 metadata blocks.
121 NOTE:
123 Versions up to 3.11 set the nodesize to 4KiB.
124 -s|--sectorsize <size>
126 Specify the sectorsize, the minimum data block allocation unit.
127 By default, the value is 4KiB, but it can be manually set to
129 match the system page size. However, if the sector size is dif‐
130 ferent from the page size, the resulting filesystem may not be
131 mountable by the current kernel, apart from the default 4KiB.
132 Hence, using this option is not advised unless you intend to
133 mount it on a system with the suitable page size.
134 -L|--label <string>
136 Specify a label for the filesystem. The string should be less
137 than 256 bytes and must not contain newline characters.
138 -K|--nodiscard
140 Do not perform whole device TRIM operation on devices that are
141 capable of that. This does not affect discard/trim operation
142 when the filesystem is mounted. Please see the mount option
143 discard for that in btrfs(5).
144 -r|--rootdir <rootdir>
146 Populate the toplevel subvolume with files from rootdir. This
147 does not require root permissions to write the new files or to
148 mount the filesystem.
149 NOTE:
151 This option may enlarge the image or file to ensure it's big
152 enough to contain the files from rootdir. Since version
153 4.14.1 the filesystem size is not minimized. Please see op‐
154 tion --shrink if you need that functionality.
155 --shrink
157 Shrink the filesystem to its minimal size, only works with
158 --rootdir option.
159 If the destination block device is a regular file, this option
161 will also truncate the file to the minimal size. Otherwise it
162 will reduce the filesystem available space. Extra space will
163 not be usable unless the filesystem is mounted and resized using
164 btrfs filesystem resize.
165 NOTE:
167 Prior to version 4.14.1, the shrinking was done automati‐
168 cally.
169 -O|--features <feature1>[,<feature2>...]
171 A list of filesystem features turned on at mkfs time. Not all
172 features are supported by old kernels. To disable a feature,
173 prefix it with ^.
174 See section FILESYSTEM FEATURES for more details. To see all
176 available features that mkfs.btrfs supports run:
177 $ mkfs.btrfs -O list-all
179 -f|--force
181 Forcibly overwrite the block devices when an existing filesystem
182 is detected. By default, mkfs.btrfs will utilize libblkid to
183 check for any known filesystem on the devices. Alternatively you
184 can use the wipefs utility to clear the devices.
185 -q|--quiet
187 Print only error or warning messages. Options --features or
188 --help are unaffected. Resets any previous effects of --ver‐
189 bose.
190 -U|--uuid <UUID>
192 Create the filesystem with the given UUID. For a single-device
193 filesystem, you can duplicate the UUID. However, for a multi-de‐
194 vice filesystem, the UUID must not already exist on any cur‐
195 rently present filesystem.
196 --device-uuid <UUID>
198 Create the filesystem with the given device-uuid UUID (also
199 known as UUID_SUB in blkid). For a single device filesystem,
200 you can duplicate the device-uuid. However, used for a multi-de‐
201 vice filesystem this option will not work at the moment.
202 -v|--verbose
204 Increase verbosity level, default is 1.
205 -V|--version
207 Print the mkfs.btrfs version and exit.
208 --help Print help.
210 -l|--leafsize <size>
212 Removed in 6.0, used to be alias for --nodesize.
213 -R|--runtime-features <feature1>[,<feature2>...]
215 Removed in 6.3, was used to specify features not affecting
216 on-disk format. Now all such features are merged into -O|--fea‐
217 tures option. The option -R will stay for backward compatibil‐
218 ity.
219
221 The default unit is byte. All size parameters accept suffixes in the
222 1024 base. The recognized suffixes are: k, m, g, t, p, e, both upper‐
223 case and lowercase.
224
226 Before mounting a multiple device filesystem, the kernel module must
227 know the association of the block devices that are attached to the
228 filesystem UUID.
229 There is typically no action needed from the user. On a system that
231 utilizes a udev-like daemon, any new block device is automatically reg‐
232 istered. The rules call btrfs device scan.
233 The same command can be used to trigger the device scanning if the
235 btrfs kernel module is reloaded (naturally all previous information
236 about the device registration is lost).
237 Another possibility is to use the mount options device to specify the
239 list of devices to scan at the time of mount.
240 # mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
242 NOTE:
244 This means only scanning, if the devices do not exist in the system,
245 mount will fail anyway. This can happen on systems without
246 initramfs/initrd and root partition created with RAID1/10/5/6 pro‐
247 files. The mount action can happen before all block devices are dis‐
248 covered. The waiting is usually done on the initramfs/initrd sys‐
249 tems.
250 WARNING:
252 RAID5/6 has known problems and should not be used in production.
253
255 Features that can be enabled during creation time. See also btrfs(5)
256 section FILESYSTEM FEATURES.
257 mixed-bg
259 (kernel support since 2.6.37)
260 mixed data and metadata block groups, also set by option --mixed
262 extref (default since btrfs-progs 3.12, kernel support since 3.7)
264 increased hardlink limit per file in a directory to 65536, older
266 kernels supported a varying number of hardlinks depending on the
267 sum of all file name sizes that can be stored into one metadata
268 block
269 raid56 (kernel support since 3.9)
271 extended format for RAID5/6, also enabled if RAID5 or RAID6
273 block groups are selected
274 skinny-metadata
276 (default since btrfs-progs 3.18, kernel support since 3.10)
277 reduced-size metadata for extent references, saves a few percent
279 of metadata
280 no-holes
282 (default since btrfs-progs 5.15, kernel support since 3.14)
283 improved representation of file extents where holes are not ex‐
285 plicitly stored as an extent, saves a few percent of metadata if
286 sparse files are used
287 zoned (kernel support since 5.12)
289 zoned mode, data allocation and write friendly to
291 zoned/SMR/ZBC/ZNS devices, see ZONED MODE in btrfs(5), the mode
292 is automatically selected when a zoned device is detected
293 quota (kernel support since 3.4)
295 Enable quota support (qgroups). The qgroup accounting will be
297 consistent, can be used together with --rootdir. See also
298 btrfs-quota(8).
299 free-space-tree
301 (default since btrfs-progs 5.15, kernel support since 4.5)
302 Enable the free space tree (mount option space_cache=v2) for
304 persisting the free space cache in a b-tree. This is built on
305 top of the COW mechanism and has better performance than v1.
306 Offline conversion from filesystems that don't have this feature
308 enabled at mkfs time is possible, see btrfstune(8).
309 Online conversion can be done by mounting with space_cache=v2,
311 this is sufficient to be done one time.
312 block-group-tree
314 (kernel support since 6.1)
315 Enable a dedicated b-tree for block group items, this greatly
317 reduces mount time for large filesystems due to better data lo‐
318 cality that avoids seeking. On rotational devices the large size
319 is considered starting from the 2-4TiB. Can be used on other
320 types of devices (SSD, NVMe, ...) as well.
321 Offline conversion from filesystems that don't have this feature
323 enabled at mkfs time is possible, see btrfstune(8). Online con‐
324 version is not possible.
325 raid-stripe-tree
327 (kernel support since 6.7)
328 New tree for logical file extent mapping where the physical map‐
330 ping may not match on multiple devices. this is now used in
331 zoned mode to implement RAID0/RAID1* profiles, but can be used
332 in non-zoned mode as well. The support for RAID56 is in develop‐
333 ment and will eventually fix the problems with the current im‐
334 plementation. This is a backward incompatible feature and has to
335 be enabled at mkfs time.
336 squota (kernel support since 6.7)
338 Enable simple quota accounting (squotas). This is an alternative
340 to qgroups with a smaller performance impact but no notion of
341 shared vs. exclusive usage.
342
344 The highlevel organizational units of a filesystem are block groups of
345 three types: data, metadata and system.
346 DATA store data blocks and nothing else
348 METADATA
350 store internal metadata in b-trees, can store file data if they
351 fit into the inline limit
352 SYSTEM store structures that describe the mapping between the physical
354 devices and the linear logical space representing the filesystem
355 Other terms commonly used:
357 block group, chunk
359 a logical range of space of a given profile, stores data, meta‐
360 data or both; sometimes the terms are used interchangeably
361 A typical size of metadata block group is 256MiB (filesystem
363 smaller than 50GiB) and 1GiB (larger than 50GiB), for data it's
364 1GiB. The system block group size is a few megabytes.
365 RAID a block group profile type that utilizes RAID-like features on
367 multiple devices: striping, mirroring, parity
368 profile
370 when used in connection with block groups refers to the alloca‐
371 tion strategy and constraints, see the section PROFILES for more
372 details
373
375 There are the following block group types available:
376 ┌─────────┬─────────────┬────────────┬────────────┬─────────────┬─────────────┐
378 │Profiles │ Redundancy │ Redundancy │ Redundancy │ Space uti‐ │ Min/max de‐ │
379 │ │ │ │ │ lization │ vices │
380 │ │ Copies │ Parity │ Striping │ │ │
381 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
382 │single │ 1 │ │ │ 100% │ 1/any │
383 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
384 │DUP │ 2 / 1 de‐ │ │ │ 50% │ 1/any (see │
385 │ │ vice │ │ │ │ note 1) │
386 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
387 │RAID0 │ 1 │ │ 1 to N │ 100% │ 1/any (see │
388 │ │ │ │ │ │ note 5) │
389 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
390 │RAID1 │ 2 │ │ │ 50% │ 2/any │
391 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
392 │RAID1C3 │ 3 │ │ │ 33% │ 3/any │
393 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
394 │RAID1C4 │ 4 │ │ │ 25% │ 4/any │
395 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
396 │RAID10 │ 2 │ │ 1 to N │ 50% │ 2/any (see │
397 │ │ │ │ │ │ note 5) │
398 └─────────┴─────────────┴────────────┴────────────┴─────────────┴─────────────┘
399 │RAID5 │ 1 │ 1 │ 2 to N-1 │ (N-1)/N │ 2/any (see │
402 │ │ │ │ │ │ note 2) │
403 ├─────────┼─────────────┼────────────┼────────────┼─────────────┼─────────────┤
404 │RAID6 │ 1 │ 2 │ 3 to N-2 │ (N-2)/N │ 3/any (see │
405 │ │ │ │ │ │ note 3) │
406 └─────────┴─────────────┴────────────┴────────────┴─────────────┴─────────────┘
407 WARNING:
409 It's not recommended to create filesystems with RAID0/1/10/5/6 pro‐
410 files on partitions from the same device. Neither redundancy nor
411 performance will be improved.
412 Note 1: DUP may exist on more than 1 device if it starts on a single
414 device and another one is added. Since version 4.5.1, mkfs.btrfs will
415 let you create DUP on multiple devices without restrictions.
416 Note 2: It's not recommended to use 2 devices with RAID5. In that case,
418 parity stripe will contain the same data as the data stripe, making
419 RAID5 degraded to RAID1 with more overhead.
420 Note 3: It's also not recommended to use 3 devices with RAID6, unless
422 you want to get effectively 3 copies in a RAID1-like manner (but not
423 exactly that).
424 Note 4: Since kernel 5.5 it's possible to use RAID1C3 as replacement
426 for RAID6, higher space cost but reliable.
427 Note 5: Since kernel 5.15 it's possible to use (mount, convert pro‐
429 files) RAID0 on one device and RAID10 on two devices.
430 PROFILE LAYOUT
432 For the following examples, assume devices numbered by 1, 2, 3 and 4,
433 data or metadata blocks A, B, C, D, with possible stripes e.g. A1, A2
434 that would be logically A, etc. For parity profiles PA and QA are par‐
435 ity and syndrome, associated with the given stripe. The simple layouts
436 single or DUP are left out. Actual physical block placement on devices
437 depends on current state of the free/allocated space and may appear
438 random. All devices are assumed to be present at the time of the blocks
439 would have been written.
440 RAID1
442 ┌─────────┬──────────┬──────────┬──────────┐
443 │device 1 │ device 2 │ device 3 │ device 4 │
444 ├─────────┼──────────┼──────────┼──────────┤
445 │A │ D │ │ │
446 ├─────────┼──────────┼──────────┼──────────┤
447 │B │ │ │ C │
448 ├─────────┼──────────┼──────────┼──────────┤
449 │C │ │ │ │
450 ├─────────┼──────────┼──────────┼──────────┤
451 │D │ A │ B │ │
452 └─────────┴──────────┴──────────┴──────────┘
453 RAID1C3
455 ┌─────────┬──────────┬──────────┬──────────┐
456 │device 1 │ device 2 │ device 3 │ device 4 │
457 ├─────────┼──────────┼──────────┼──────────┤
458 │A │ A │ D │ │
459 ├─────────┼──────────┼──────────┼──────────┤
460 │B │ │ B │ │
461 ├─────────┼──────────┼──────────┼──────────┤
462 │C │ │ A │ C │
463 ├─────────┼──────────┼──────────┼──────────┤
464 │D │ D │ C │ B │
465 └─────────┴──────────┴──────────┴──────────┘
466 RAID0
468 ────────────────────────────────────────────
469 device 1 device 2 device 3 device 4
470 ────────────────────────────────────────────
471 A2 C3 A3 C2
472 ────────────────────────────────────────────
473 B1 A1 D2 B3
474 ────────────────────────────────────────────
475 C1 D3 B4 D1
476 ────────────────────────────────────────────
477 D4 B2 C4 A4
478 ┌─────────┬──────────┬──────────┬──────────┐
479 │ │ │ │ │
480 RAID5 │ │ │ │ │
481 ├─────────┼──────────┼──────────┼──────────┤
482 │device 1 │ device 2 │ device 3 │ device 4 │
483 ├─────────┼──────────┼──────────┼──────────┤
484 │A2 │ C3 │ A3 │ C2 │
485 ├─────────┼──────────┼──────────┼──────────┤
486 │B1 │ A1 │ D2 │ B3 │
487 ├─────────┼──────────┼──────────┼──────────┤
488 │C1 │ D3 │ PB │ D1 │
489 ├─────────┼──────────┼──────────┼──────────┤
490 │PD │ B2 │ PC │ PA │
491 ├─────────┼──────────┼──────────┼──────────┤
492 │ │ │ │ │
493 RAID6 │ │ │ │ │
494 ├─────────┼──────────┼──────────┼──────────┤
495 │device 1 │ device 2 │ device 3 │ device 4 │
496 ├─────────┼──────────┼──────────┼──────────┤
497 │A2 │ QC │ QA │ C2 │
498 ├─────────┼──────────┼──────────┼──────────┤
499 │B1 │ A1 │ D2 │ QB │
500 ├─────────┼──────────┼──────────┼──────────┤
501 │C1 │ QD │ PB │ D1 │
502 ├─────────┼──────────┼──────────┼──────────┤
503 │PD │ B2 │ PC │ PA │
504 ├─────────┼──────────┼──────────┼──────────┤
505 │ │ │ │ │
507 The mkfs uti│lity will│let the us│er create a│filesystem│with profiles
508 that write the│logical b│locks to 2 │physical l│ocations. │Whether there
509 are really 2│ physical│copies hig│hly depends│on the und│erlying device
510 type. │ │ │ │ │
511 │ │ │ │ │
512 For example, a│SSD drive│can remap │the blocks │internally │to a single
513 copy--thus de│duplicatin│g them. T│his negates│the purpos│e of increased
514 redundancy and│just wast│es filesyst│em space wi│thout provi│ding the ex‐
515 pected level o│f redundan│cy. │ │ │
516 │ │ │ │ │
517 The duplicate│d data/me│tadata may │still be us│eful to sta│tistically im‐
518 prove the chan│ces on a d│evice that │might perfo│rm some i│nternal opti‐
519 mizations. The│actual de│tails are n│ot usually │disclosed b│y vendors. For
520 example we cou│ld expect │that not al│l blocks ge│t deduplica│ted. This will
521 provide a non-│zero proba│bility of r│ecovery com│pared to a │zero chance if
522 the single pro│file is us│ed. The use│r should ma│ke the trad│eoff decision.
523 The deduplicat│ion in SSD│s is though│t to be wid│ely availab│le so the rea‐
524 son behind the│mkfs defa│ult is to n│ot give a f│alse sense │of redundancy.
525 │ │ │ │ │
526 As another exa│mple, the │widely used│USB flash │or SD cards│use a trans‐
527 lation layer │between t│he logical │and physica│l view of t│he device. The
528 data lifetime │may be aff│ected by fr│equent plug│ging. The │memory cells
529 could get da│maged, hop│efully not │destroying │both copies│of particular
530 data in case o│f DUP. │ │ │ │
531 │ │ │ │ │
532 The wear level│ling techn│iques can a│lso lead to│reduced re│dundancy, even
533 if the devic│e does no│t do any de│duplication│. The contr│ollers may put
534 data written i│n a short │timespan in│to the same│ physical │storage unit
535 (cell, block │etc). In c│ase this un│it dies, bo│th copies a│re lost. BTRFS
536 does not add a│ny artific│ial delay b│etween meta│data writes│.
537 │ │ │ │ │
538 The traditional rotational hard drives usually fail at the sector
539 level.
540 In any case, a device that starts to misbehave and repairs from the DUP
542 copy should be replaced! DUP is not backup.
543
545 SMALL FILESYSTEMS AND LARGE NODESIZE
546 The combination of small filesystem size and large nodesize is not rec‐
548 ommended in general and can lead to various ENOSPC-related issues dur‐
549 ing mount time or runtime.
550 Since mixed block group creation is optional, we allow small filesystem
552 instances with differing values for sectorsize and nodesize to be cre‐
553 ated and could end up in the following situation:
554 # mkfs.btrfs -f -n 65536 /dev/loop0
556 btrfs-progs v3.19-rc2-405-g976307c
557 See https://btrfs.readthedocs.io for more information.
558 Performing full device TRIM (512.00MiB) ...
560 Label: (null)
561 UUID: 49fab72e-0c8b-466b-a3ca-d1bfe56475f0
562 Node size: 65536
563 Sector size: 4096
564 Filesystem size: 512.00MiB
565 Block group profiles:
566 Data: single 8.00MiB
567 Metadata: DUP 40.00MiB
568 System: DUP 12.00MiB
569 SSD detected: no
570 Incompat features: extref, skinny-metadata
571 Number of devices: 1
572 Devices:
573 ID SIZE PATH
574 1 512.00MiB /dev/loop0
575 # mount /dev/loop0 /mnt/
577 mount: mount /dev/loop0 on /mnt failed: No space left on device
578 The ENOSPC occurs during the creation of the UUID tree. This is caused
580 by large metadata blocks and space reservation strategy that allocates
581 more than can fit into the filesystem.
582
584 btrfs is part of btrfs-progs. Please refer to the documentation at
585 https://btrfs.readthedocs.io.
586
588 btrfs(5), btrfs(8), btrfs-balance(8), wipefs(8)
5896.6.2 Nov 24, 2023 MKFS.BTRFS(8)