1MKFS.BTRFS(8) Btrfs Manual 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
13 multiple devices. <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 detals and
25 btrfs-balance(8) for the profile conversion post mkfs.
26
28 -b|--byte-count <size>
29 Specify the size of the filesystem. If this option is not used,
30 then mkfs.btrfs uses the entire device space for the filesystem.
31 --csum <type>, --checksum <type>
33 Specify the checksum algorithm. Default is crc32c. Valid values are
34 crc32c, xxhash, sha256 or blake2. To mount such filesystem kernel
35 must support the checksums as well. See CHECKSUM ALGORITHMS in
36 btrfs(5).
37 -d|--data <profile>
39 Specify the profile for the data block groups. Valid values are
40 raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10 or single or
41 dup (case does not matter).
42 See DUP PROFILES ON A SINGLE DEVICE for more details.
44 On multiple devices, the default was raid0 until version 5.7, while
46 it is single since version 5.8. You can still select raid0
47 manually, but it was not suitable as default.
48 -m|--metadata <profile>
50 Specify the profile for the metadata block groups. Valid values are
51 raid0, raid1, raid1c3, raid1c4, raid5, raid6, raid10, single or dup
52 (case does not matter).
53 Default on a single device filesystem is DUP and is recommended for
55 metadata in general. The duplication might not be necessary in some
56 use cases and it’s up to the user to changed that at mkfs time or
57 later. This depends on hardware that could potentially deduplicate
58 the blocks again but this cannot be detected at mkfs time.
59 NOTE
61 Up to version 5.14 there was a detection of a SSD device (more
62 precisely if it’s a rotational device, determined by the
63 contents of file /sys/block/DEV/queue/rotational) that used to
64 select single. This has changed in version 5.15 to be always
65 dup.
66 Note that the rotational status can be arbitrarily set by the
68 underlying block device driver and may not reflect the true
69 status (network block device, memory-backed SCSI devices, real
70 block device behind some additonal device mapper layer, etc).
71 It’s recommended to always set the options --data/--metadata to
72 avoid confusion and unexpected results.
73 See DUP PROFILES ON A SINGLE DEVICE for more details.
75 On multiple devices the default is raid1.
76 -M|--mixed
78 Normally the data and metadata block groups are isolated. The mixed
79 mode will remove the isolation and store both types in the same
80 block group type. This helps to utilize the free space regardless
81 of the purpose and is suitable for small devices. The separate
82 allocation of block groups leads to a situation where the space is
83 reserved for the other block group type, is not available for
84 allocation and can lead to ENOSPC state.
85 The recommended size for the mixed mode is for filesystems less
87 than 1GiB. The soft recommendation is to use it for filesystems
88 smaller than 5GiB. The mixed mode may lead to degraded performance
89 on larger filesystems, but is otherwise usable, even on multiple
90 devices.
91 The nodesize and sectorsize must be equal, and the block group
93 types must match.
94 Note
96 versions up to 4.2.x forced the mixed mode for devices smaller
97 than 1GiB. This has been removed in 4.3+ as it caused some
98 usability issues.
99 -l|--leafsize <size>
101 Alias for --nodesize. Deprecated.
102 -n|--nodesize <size>
104 Specify the nodesize, the tree block size in which btrfs stores
105 metadata. The default value is 16KiB (16384) or the page size,
106 whichever is bigger. Must be a multiple of the sectorsize and a
107 power of 2, but not larger than 64KiB (65536). Leafsize always
108 equals nodesize and the options are aliases.
109 Smaller node size increases fragmentation but leads to taller
111 b-trees which in turn leads to lower locking contention. Higher
112 node sizes give better packing and less fragmentation at the cost
113 of more expensive memory operations while updating the metadata
114 blocks.
115 Note
117 versions up to 3.11 set the nodesize to 4k.
118 -s|--sectorsize <size>
120 Specify the sectorsize, the minimum data block allocation unit.
121 The default value is the page size and is autodetected. If the
123 sectorsize differs from the page size, the created filesystem may
124 not be mountable by the running kernel. Therefore it is not
125 recommended to use this option unless you are going to mount it on
126 a system with the appropriate page size.
127 -L|--label <string>
129 Specify a label for the filesystem. The string should be less than
130 256 bytes and must not contain newline characters.
131 -K|--nodiscard
133 Do not perform whole device TRIM operation on devices that are
134 capable of that. This does not affect discard/trim operation when
135 the filesystem is mounted. Please see the mount option discard for
136 that in btrfs(5).
137 -r|--rootdir <rootdir>
139 Populate the toplevel subvolume with files from rootdir. This does
140 not require root permissions to write the new files or to mount the
141 filesystem.
142 Note
144 This option may enlarge the image or file to ensure it’s big
145 enough to contain the files from rootdir. Since version 4.14.1
146 the filesystem size is not minimized. Please see option
147 --shrink if you need that functionality.
148 --shrink
150 Shrink the filesystem to its minimal size, only works with
151 --rootdir option.
152 If the destination block device is a regular file, this option will
154 also truncate the file to the minimal size. Otherwise it will
155 reduce the filesystem available space. Extra space will not be
156 usable unless the filesystem is mounted and resized using btrfs
157 filesystem resize.
158 Note
160 prior to version 4.14.1, the shrinking was done automatically.
161 -O|--features <feature1>[,<feature2>...]
163 A list of filesystem features turned on at mkfs time. Not all
164 features are supported by old kernels. To disable a feature, prefix
165 it with ^.
166 See section FILESYSTEM FEATURES for more details. To see all
168 available features that mkfs.btrfs supports run:
169 mkfs.btrfs -O list-all
171 -R|--runtime-features <feature1>[,<feature2>...]
173 A list of features that be can enabled at mkfs time, otherwise
174 would have to be turned on a mounted filesystem. Although no
175 runtime feature is enabled by default, to disable a feature, prefix
176 it with ^.
177 See section RUNTIME FEATURES for more details. To see all available
179 runtime features that mkfs.btrfs supports run:
180 mkfs.btrfs -R list-all
182 -f|--force
184 Forcibly overwrite the block devices when an existing filesystem is
185 detected. By default, mkfs.btrfs will utilize libblkid to check for
186 any known filesystem on the devices. Alternatively you can use the
187 wipefs utility to clear the devices.
188 -q|--quiet
190 Print only error or warning messages. Options --features or --help
191 are unaffected. Resets any previous effects of --verbose.
192 -U|--uuid <UUID>
194 Create the filesystem with the given UUID. The UUID must not exist
195 on any filesystem currently present.
196 -v|--verbose
198 Increase verbosity level, default is 1.
199 -V|--version
201 Print the mkfs.btrfs version and exit.
202 --help
204 Print help.
205
207 The default unit is byte. All size parameters accept suffixes in the
208 1024 base. The recognized suffixes are: k, m, g, t, p, e, both
209 uppercase and lowercase.
210
212 Before mounting a multiple device filesystem, the kernel module must
213 know the association of the block devices that are attached to the
214 filesystem UUID.
215 There is typically no action needed from the user. On a system that
217 utilizes a udev-like daemon, any new block device is automatically
218 registered. The rules call btrfs device scan.
219 The same command can be used to trigger the device scanning if the
221 btrfs kernel module is reloaded (naturally all previous information
222 about the device registration is lost).
223 Another possibility is to use the mount options device to specify the
225 list of devices to scan at the time of mount.
226 # mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt
228 Note
231 that this means only scanning, if the devices do not exist in the
232 system, mount will fail anyway. This can happen on systems without
233 initramfs/initrd and root partition created with RAID1/10/5/6
234 profiles. The mount action can happen before all block devices are
235 discovered. The waiting is usually done on the initramfs/initrd
236 systems.
237 RAID5/6 has known problems and should not be used in production.
239
241 Features that can be enabled during creation time. See also btrfs(5)
242 section FILESYSTEM FEATURES.
243 mixed-bg
245 (kernel support since 2.6.37)
246 mixed data and metadata block groups, also set by option --mixed
248 extref
250 (default since btrfs-progs 3.12, kernel support since 3.7)
251 increased hardlink limit per file in a directory to 65536, older
253 kernels supported a varying number of hardlinks depending on the
254 sum of all file name sizes that can be stored into one metadata
255 block
256 raid56
258 (kernel support since 3.9)
259 extended format for RAID5/6, also enabled if raid5 or raid6 block
261 groups are selected
262 skinny-metadata
264 (default since btrfs-progs 3.18, kernel support since 3.10)
265 reduced-size metadata for extent references, saves a few percent of
267 metadata
268 no-holes
270 (default since btrfs-progs 5.15, kernel support since 3.14)
271 improved representation of file extents where holes are not
273 explicitly stored as an extent, saves a few percent of metadata if
274 sparse files are used
275 zoned
277 (kernel support since 5.12)
278 zoned mode, data allocation and write friendly to zoned/SMR/ZBC/ZNS
280 devices, see ZONED MODE in btrfs(5), the mode is automatically
281 selected when a zoned device is detected
282
284 Features that are typically enabled on a mounted filesystem, eg. by a
285 mount option or by an ioctl. Some of them can be enabled early, at mkfs
286 time. This applies to features that need to be enabled once and then
287 the status is permanent, this does not replace mount options.
288 quota
290 (kernel support since 3.4)
291 Enable quota support (qgroups). The qgroup accounting will be
293 consistent, can be used together with --rootdir. See also
294 btrfs-quota(8).
295 free-space-tree
297 (default since btrfs-progs 5.15, kernel support since 4.5)
298 Enable the free space tree (mount option space_cache=v2) for
300 persisting the free space cache.
301
303 The highlevel organizational units of a filesystem are block groups of
304 three types: data, metadata and system.
305 DATA
307 store data blocks and nothing else
308 METADATA
310 store internal metadata in b-trees, can store file data if they fit
311 into the inline limit
312 SYSTEM
314 store structures that describe the mapping between the physical
315 devices and the linear logical space representing the filesystem
316 Other terms commonly used:
318 block group, chunk
320 a logical range of space of a given profile, stores data, metadata
321 or both; sometimes the terms are used interchangeably
322 A typical size of metadata block group is 256MiB (filesystem
324 smaller than 50GiB) and 1GiB (larger than 50GiB), for data it’s
325 1GiB. The system block group size is a few megabytes.
326 RAID
328 a block group profile type that utilizes RAID-like features on
329 multiple devices: striping, mirroring, parity
330 profile
332 when used in connection with block groups refers to the allocation
333 strategy and constraints, see the section PROFILES for more details
334
336 There are the following block group types available:
337 ┌────────┬────────────────────────────┬─────────────┬─────────────┐
339 │ │ │ │ │
340 │Profile │ Redundancy │ Space │ Min/max │
341 │ ├────────┬────────┬──────────┤ utilization │ devices │
342 │ │ │ │ │ │ │
343 │ │ Copies │ Parity │ Striping │ │ │
344 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
345 │ │ │ │ │ │ │
346 │single │ 1 │ │ │ 100% │ 1/any │
347 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
348 │ │ │ │ │ │ │
349 │DUP │ 2 / 1 │ │ │ 50% │ 1/any ^(see │
350 │ │ device │ │ │ │ note 1) │
351 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
352 │ │ │ │ │ │ │
353 │RAID0 │ │ │ 1 to N │ 100% │ 1/any ^(see │
354 │ │ │ │ │ │ note 5) │
355 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
356 │ │ │ │ │ │ │
357 │RAID1 │ 2 │ │ │ 50% │ 2/any │
358 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
359 │ │ │ │ │ │ │
360 │RAID1C3 │ 3 │ │ │ 33% │ 3/any │
361 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
362 │ │ │ │ │ │ │
363 │RAID1C4 │ 4 │ │ │ 25% │ 4/any │
364 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
365 │ │ │ │ │ │ │
366 │RAID10 │ 2 │ │ 1 to N │ 50% │ 2/any ^(see │
367 │ │ │ │ │ │ note 5) │
368 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
369 │ │ │ │ │ │ │
370 │RAID5 │ 1 │ 1 │ 2 to N-1 │ (N-1)/N │ 2/any ^(see │
371 │ │ │ │ │ │ note 2) │
372 ├────────┼────────┼────────┼──────────┼─────────────┼─────────────┤
373 │ │ │ │ │ │ │
374 │RAID6 │ 1 │ 2 │ 3 to N-2 │ (N-2)/N │ 3/any ^(see │
375 │ │ │ │ │ │ note 3) │
376 └────────┴────────┴────────┴──────────┴─────────────┴─────────────┘
377 Warning
379 It’s not recommended to create filesystems with RAID0/1/10/5/6
380 profiles on partitions from the same device. Neither redundancy nor
381 performance will be improved.
382 Note 1: DUP may exist on more than 1 device if it starts on a single
384 device and another one is added. Since version 4.5.1, mkfs.btrfs will
385 let you create DUP on multiple devices without restrictions.
386 Note 2: It’s not recommended to use 2 devices with RAID5. In that case,
388 parity stripe will contain the same data as the data stripe, making
389 RAID5 degraded to RAID1 with more overhead.
390 Note 3: It’s also not recommended to use 3 devices with RAID6, unless
392 you want to get effectively 3 copies in a RAID1-like manner (but not
393 exactly that).
394 Note 4: Since kernel 5.5 it’s possible to use RAID1C3 as replacement
396 for RAID6, higher space cost but reliable.
397 Note 5: Since kernel 5.15 it’s possible to use (mount, convert
399 profiles) RAID0 on one device and RAID10 on two devices.
400 PROFILE LAYOUT
402 For the following examples, assume devices numbered by 1, 2, 3 and 4,
403 data or metadata blocks A, B, C, D, with possible stripes eg. A1, A2
404 that would be logically A, etc. For parity profiles PA and QA are
405 parity and syndrom, associated with the given stripe. The simple
406 layouts single or DUP are left out. Actual physical block placement on
407 devices depends on current state of the free/allocated space and may
408 appear random. All devices are assumed to be present at the time of the
409 blocks would have been written.
410 RAID1
412 ┌─────────┬──────────┬──────────┬──────────┐
414 │device 1 │ device 2 │ device 3 │ device 4 │
415 ├─────────┼──────────┼──────────┼──────────┤
416 │ │ │ │ │
417 │ A │ D │ │ │
418 ├─────────┼──────────┼──────────┼──────────┤
419 │ │ │ │ │
420 │ B │ │ │ C │
421 ├─────────┼──────────┼──────────┼──────────┤
422 │ │ │ │ │
423 │ C │ │ │ │
424 ├─────────┼──────────┼──────────┼──────────┤
425 │ │ │ │ │
426 │ D │ A │ B │ │
427 └─────────┴──────────┴──────────┴──────────┘
428 RAID1C3
430 ┌─────────┬──────────┬──────────┬──────────┐
432 │device 1 │ device 2 │ device 3 │ device 4 │
433 ├─────────┼──────────┼──────────┼──────────┤
434 │ │ │ │ │
435 │ A │ A │ D │ │
436 ├─────────┼──────────┼──────────┼──────────┤
437 │ │ │ │ │
438 │ B │ │ B │ │
439 ├─────────┼──────────┼──────────┼──────────┤
440 │ │ │ │ │
441 │ C │ │ A │ C │
442 ├─────────┼──────────┼──────────┼──────────┤
443 │ │ │ │ │
444 │ D │ D │ C │ B │
445 └─────────┴──────────┴──────────┴──────────┘
446 RAID0
448 ┌─────────┬──────────┬──────────┬──────────┐
450 │device 1 │ device 2 │ device 3 │ device 4 │
451 ├─────────┼──────────┼──────────┼──────────┤
452 │ │ │ │ │
453 │ A2 │ C3 │ A3 │ C2 │
454 ├─────────┼──────────┼──────────┼──────────┤
455 │ │ │ │ │
456 │ B1 │ A1 │ D2 │ B3 │
457 ├─────────┼──────────┼──────────┼──────────┤
458 │ │ │ │ │
459 │ C1 │ D3 │ B4 │ D1 │
460 ├─────────┼──────────┼──────────┼──────────┤
461 │ │ │ │ │
462 │ D4 │ B2 │ C4 │ A4 │
463 └─────────┴──────────┴──────────┴──────────┘
464 RAID5
466 ┌─────────┬──────────┬──────────┬──────────┐
468 │device 1 │ device 2 │ device 3 │ device 4 │
469 ├─────────┼──────────┼──────────┼──────────┤
470 │ │ │ │ │
471 │ A2 │ C3 │ A3 │ C2 │
472 ├─────────┼──────────┼──────────┼──────────┤
473 │ │ │ │ │
474 │ B1 │ A1 │ D2 │ B3 │
475 ├─────────┼──────────┼──────────┼──────────┤
476 │ │ │ │ │
477 │ C1 │ D3 │ PB │ D1 │
478 ├─────────┼──────────┼──────────┼──────────┤
479 │ │ │ │ │
480 │ PD │ B2 │ PC │ PA │
481 └─────────┴──────────┴──────────┴──────────┘
482 RAID6
484 ┌─────────┬──────────┬──────────┬──────────┐
486 │device 1 │ device 2 │ device 3 │ device 4 │
487 ├─────────┼──────────┼──────────┼──────────┤
488 │ │ │ │ │
489 │ A2 │ QC │ QA │ C2 │
490 ├─────────┼──────────┼──────────┼──────────┤
491 │ │ │ │ │
492 │ B1 │ A1 │ D2 │ QB │
493 ├─────────┼──────────┼──────────┼──────────┤
494 │ │ │ │ │
495 │ C1 │ QD │ PB │ D1 │
496 ├─────────┼──────────┼──────────┼──────────┤
497 │ │ │ │ │
498 │ PD │ B2 │ PC │ PA │
499 └─────────┴──────────┴──────────┴──────────┘
500
502 The mkfs utility will let the user create a filesystem with profiles
503 that write the logical blocks to 2 physical locations. Whether there
504 are really 2 physical copies highly depends on the underlying device
505 type.
506 For example, a SSD drive can remap the blocks internally to a single
508 copy—thus deduplicating them. This negates the purpose of increased
509 redundancy and just wastes filesystem space without providing the
510 expected level of redundancy.
511 The duplicated data/metadata may still be useful to statistically
513 improve the chances on a device that might perform some internal
514 optimizations. The actual details are not usually disclosed by vendors.
515 For example we could expect that not all blocks get deduplicated. This
516 will provide a non-zero probability of recovery compared to a zero
517 chance if the single profile is used. The user should make the tradeoff
518 decision. The deduplication in SSDs is thought to be widely available
519 so the reason behind the mkfs default is to not give a false sense of
520 redundancy.
521 As another example, the widely used USB flash or SD cards use a
523 translation layer between the logical and physical view of the device.
524 The data lifetime may be affected by frequent plugging. The memory
525 cells could get damaged, hopefully not destroying both copies of
526 particular data in case of DUP.
527 The wear levelling techniques can also lead to reduced redundancy, even
529 if the device does not do any deduplication. The controllers may put
530 data written in a short timespan into the same physical storage unit
531 (cell, block etc). In case this unit dies, both copies are lost. BTRFS
532 does not add any artificial delay between metadata writes.
533 The traditional rotational hard drives usually fail at the sector
535 level.
536 In any case, a device that starts to misbehave and repairs from the DUP
538 copy should be replaced! DUP is not backup.
539
541 SMALL FILESYSTEMS AND LARGE NODESIZE
542 The combination of small filesystem size and large nodesize is not
544 recommended in general and can lead to various ENOSPC-related issues
545 during mount time or runtime.
546 Since mixed block group creation is optional, we allow small filesystem
548 instances with differing values for sectorsize and nodesize to be
549 created and could end up in the following situation:
550 # mkfs.btrfs -f -n 65536 /dev/loop0
552 btrfs-progs v3.19-rc2-405-g976307c
553 See http://btrfs.wiki.kernel.org for more information.
554 Performing full device TRIM (512.00MiB) ...
556 Label: (null)
557 UUID: 49fab72e-0c8b-466b-a3ca-d1bfe56475f0
558 Node size: 65536
559 Sector size: 4096
560 Filesystem size: 512.00MiB
561 Block group profiles:
562 Data: single 8.00MiB
563 Metadata: DUP 40.00MiB
564 System: DUP 12.00MiB
565 SSD detected: no
566 Incompat features: extref, skinny-metadata
567 Number of devices: 1
568 Devices:
569 ID SIZE PATH
570 1 512.00MiB /dev/loop0
571 # mount /dev/loop0 /mnt/
573 mount: mount /dev/loop0 on /mnt failed: No space left on device
574 The ENOSPC occurs during the creation of the UUID tree. This is caused
576 by large metadata blocks and space reservation strategy that allocates
577 more than can fit into the filesystem.
578
580 mkfs.btrfs is part of btrfs-progs. Please refer to the btrfs wiki
581 http://btrfs.wiki.kernel.org for further details.
582
584 btrfs(5), btrfs(8), btrfs-balance(8), wipefs(8)
585Btrfs v5.15.1 11/22/2021 MKFS.BTRFS(8)