| 1 |
.\" Man page generated from reStructuredText |
| 2 |
.\" by the Docutils 0.22.4 manpage writer. |
| 3 |
. |
| 4 |
. |
| 5 |
.nr rst2man-indent-level 0 |
| 6 |
. |
| 7 |
.de1 rstReportMargin |
| 8 |
\\$1 \\n[an-margin] |
| 9 |
level \\n[rst2man-indent-level] |
| 10 |
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 11 |
- |
| 12 |
\\n[rst2man-indent0] |
| 13 |
\\n[rst2man-indent1] |
| 14 |
\\n[rst2man-indent2] |
| 15 |
.. |
| 16 |
.de1 INDENT |
| 17 |
.\" .rstReportMargin pre: |
| 18 |
. RS \\$1 |
| 19 |
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| 20 |
. nr rst2man-indent-level +1 |
| 21 |
.\" .rstReportMargin post: |
| 22 |
.. |
| 23 |
.de UNINDENT |
| 24 |
. RE |
| 25 |
.\" indent \\n[an-margin] |
| 26 |
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 27 |
.nr rst2man-indent-level -1 |
| 28 |
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 29 |
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| 30 |
.. |
| 31 |
.TH "BTRFS-CHECK" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-check \- check or repair a btrfs filesystem |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs check\fP [options] <device> |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
The filesystem checker is used to verify structural integrity of a filesystem |
| 40 |
and attempt to repair it if requested. It is recommended to unmount the |
| 41 |
filesystem prior to running the check, but it is possible to start checking a |
| 42 |
mounted filesystem (see \-\-force). |
| 43 |
.sp |
| 44 |
By default, \fBbtrfs check\fP will not modify the device but you can reaffirm that |
| 45 |
by the option \fI\-\-readonly\fP\&. |
| 46 |
.sp |
| 47 |
\fBbtrfsck\fP is an alias of \fBbtrfs check\fP command and is now deprecated. |
| 48 |
.sp |
| 49 |
\fBNote:\fP |
| 50 |
.INDENT 0.0 |
| 51 |
.INDENT 3.5 |
| 52 |
Even though the filesystem checker requires a device argument, it scans for all |
| 53 |
devices belonging to the same filesystem, thus it should not cause a difference |
| 54 |
using different devices of the same filesystem. |
| 55 |
Furthermore btrfs\-check(8) \%<> will automatically choose the good mirror, thus as long |
| 56 |
as there is a good copy for metadata, it will not report such case as an error. |
| 57 |
.UNINDENT |
| 58 |
.UNINDENT |
| 59 |
.sp |
| 60 |
\fBWarning:\fP |
| 61 |
.INDENT 0.0 |
| 62 |
.INDENT 3.5 |
| 63 |
Do not use \fI\-\-repair\fP unless you are advised to do so by a developer |
| 64 |
or an experienced user, and then only after having accepted that no \fIfsck\fP |
| 65 |
successfully repair all types of filesystem corruption. E.g. some other software |
| 66 |
or hardware bugs can fatally damage a volume. |
| 67 |
.UNINDENT |
| 68 |
.UNINDENT |
| 69 |
.sp |
| 70 |
The structural integrity check verifies if internal filesystem objects or |
| 71 |
data structures satisfy the constraints, point to the right objects or are |
| 72 |
correctly connected together. |
| 73 |
.sp |
| 74 |
There are several cross checks that can detect wrong reference counts of shared |
| 75 |
extents, backreferences, missing extents of inodes, directory and inode |
| 76 |
connectivity etc. |
| 77 |
.sp |
| 78 |
The amount of memory required can be high, depending on the size of the |
| 79 |
filesystem, similarly the run time. Check the modes that can also affect that. |
| 80 |
.SH SAFE OR ADVISORY OPTIONS |
| 81 |
.INDENT 0.0 |
| 82 |
.TP |
| 83 |
.B \-b|\-\-backup |
| 84 |
use the first valid set of backup roots stored in the superblock |
| 85 |
.sp |
| 86 |
This can be combined with \fI\-\-super\fP if some of the superblocks are damaged. |
| 87 |
.UNINDENT |
| 88 |
.INDENT 0.0 |
| 89 |
.TP |
| 90 |
.B \-\-check\-data\-csum |
| 91 |
verify checksums of data blocks |
| 92 |
.sp |
| 93 |
This expects that the filesystem is otherwise OK, and is basically an offline |
| 94 |
\fIscrub\fP that does not repair data from spare copies. |
| 95 |
.TP |
| 96 |
.BI \-\-chunk\-root \ <bytenr> |
| 97 |
use the given offset \fIbytenr\fP for the chunk tree root |
| 98 |
.UNINDENT |
| 99 |
.INDENT 0.0 |
| 100 |
.TP |
| 101 |
.B \-E|\-\-subvol\-extents <subvolid> |
| 102 |
show extent state for the given subvolume |
| 103 |
.UNINDENT |
| 104 |
.INDENT 0.0 |
| 105 |
.TP |
| 106 |
.BI \-\-mode \ <MODE> |
| 107 |
select mode of operation regarding memory and IO |
| 108 |
.sp |
| 109 |
The \fIMODE\fP can be one of: |
| 110 |
.INDENT 7.0 |
| 111 |
.TP |
| 112 |
.B original |
| 113 |
The metadata are read into memory and verified, thus the requirements are high |
| 114 |
on large filesystems and can even lead to out\-of\-memory conditions. The |
| 115 |
possible workaround is to export the block device over network to a machine |
| 116 |
with enough memory. |
| 117 |
.TP |
| 118 |
.B lowmem |
| 119 |
This mode is supposed to address the high memory consumption at the cost of |
| 120 |
increased IO when it needs to re\-read blocks. This may increase run time. |
| 121 |
.UNINDENT |
| 122 |
.UNINDENT |
| 123 |
.INDENT 0.0 |
| 124 |
.TP |
| 125 |
.B \-p|\-\-progress |
| 126 |
indicate progress at various checking phases |
| 127 |
.TP |
| 128 |
.B \-Q|\-\-qgroup\-report |
| 129 |
verify qgroup accounting and compare against filesystem accounting |
| 130 |
.TP |
| 131 |
.B \-r|\-\-tree\-root <bytenr> |
| 132 |
use the given offset \(aqbytenr\(aq for the tree root |
| 133 |
.UNINDENT |
| 134 |
.INDENT 0.0 |
| 135 |
.TP |
| 136 |
.B \-\-readonly |
| 137 |
(default) |
| 138 |
run in read\-only mode, this option exists to calm potential panic when users |
| 139 |
are going to run the checker |
| 140 |
.UNINDENT |
| 141 |
.INDENT 0.0 |
| 142 |
.TP |
| 143 |
.B \-s|\-\-super <N> |
| 144 |
use Nth superblock copy, valid values are 0, 1 or 2 if the |
| 145 |
respective superblock offset is within the device size |
| 146 |
.sp |
| 147 |
This can be used to use a different starting point if some of the primary |
| 148 |
superblock is damaged. |
| 149 |
.UNINDENT |
| 150 |
.SH DANGEROUS OPTIONS |
| 151 |
.INDENT 0.0 |
| 152 |
.TP |
| 153 |
.B \-\-repair |
| 154 |
enable the repair mode and attempt to fix problems where possible |
| 155 |
.sp |
| 156 |
\fBNote:\fP |
| 157 |
.INDENT 7.0 |
| 158 |
.INDENT 3.5 |
| 159 |
There\(aqs a warning and 10 second delay when this option is run without |
| 160 |
\fI\-\-force\fP to give users a chance to think twice before running repair, the |
| 161 |
warnings in documentation have shown to be insufficient. |
| 162 |
.UNINDENT |
| 163 |
.UNINDENT |
| 164 |
.sp |
| 165 |
\fBNote:\fP |
| 166 |
.INDENT 7.0 |
| 167 |
.INDENT 3.5 |
| 168 |
Please finish/cancel the running replace/balance before using this command. |
| 169 |
.UNINDENT |
| 170 |
.UNINDENT |
| 171 |
.TP |
| 172 |
.B \-\-init\-csum\-tree |
| 173 |
create a new checksum tree and recalculate checksums in all files |
| 174 |
.sp |
| 175 |
\fBWarning:\fP |
| 176 |
.INDENT 7.0 |
| 177 |
.INDENT 3.5 |
| 178 |
Do not blindly use this option to fix checksum mismatch problems. |
| 179 |
.UNINDENT |
| 180 |
.UNINDENT |
| 181 |
.TP |
| 182 |
.B \-\-init\-extent\-tree |
| 183 |
build the extent tree from scratch |
| 184 |
.sp |
| 185 |
\fBWarning:\fP |
| 186 |
.INDENT 7.0 |
| 187 |
.INDENT 3.5 |
| 188 |
Do not use unless you know what you\(aqre doing. |
| 189 |
.UNINDENT |
| 190 |
.UNINDENT |
| 191 |
.UNINDENT |
| 192 |
.INDENT 0.0 |
| 193 |
.TP |
| 194 |
.B \-\-force |
| 195 |
allow work on a mounted filesystem and skip mount checks. Note that |
| 196 |
this should work fine on a quiescent or read\-only mounted filesystem |
| 197 |
but may crash if the device is changed externally, e.g. by the kernel |
| 198 |
module. |
| 199 |
.sp |
| 200 |
\fBNote:\fP |
| 201 |
.INDENT 7.0 |
| 202 |
.INDENT 3.5 |
| 203 |
It is possible to run with \-\-repair but on a mounted filesystem |
| 204 |
that will most likely lead to a corruption unless the filesystem |
| 205 |
is in a quiescent state which may not be possible to guarantee. |
| 206 |
.UNINDENT |
| 207 |
.UNINDENT |
| 208 |
.sp |
| 209 |
This option also skips the delay and warning in the repair mode (see |
| 210 |
\fI\-\-repair\fP). |
| 211 |
.UNINDENT |
| 212 |
.SH DEPRECATED OR REMOVED OPTIONS |
| 213 |
.INDENT 0.0 |
| 214 |
.TP |
| 215 |
.B \-\-clear\-space\-cache v1|v2 |
| 216 |
completely remove the free space cache of the given version |
| 217 |
.sp |
| 218 |
See also the \fIclear_cache\fP mount option. |
| 219 |
.sp |
| 220 |
\fBWarning:\fP |
| 221 |
.INDENT 7.0 |
| 222 |
.INDENT 3.5 |
| 223 |
This option is deprecated, please use \fIbtrfs rescue clear\-space\-cache\fP |
| 224 |
instead, this option would be removed in the future eventually. |
| 225 |
.UNINDENT |
| 226 |
.UNINDENT |
| 227 |
.UNINDENT |
| 228 |
.SH EXIT STATUS |
| 229 |
.sp |
| 230 |
\fBbtrfs check\fP returns a zero exit status if it succeeds. Non zero is |
| 231 |
returned in case of failure. |
| 232 |
.SH AVAILABILITY |
| 233 |
.sp |
| 234 |
\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at |
| 235 |
\%<https://\:btrfs\:.readthedocs\:.io>\&. |
| 236 |
.SH SEE ALSO |
| 237 |
.sp |
| 238 |
mkfs.btrfs(8) \%<>, |
| 239 |
btrfs\-scrub(8) \%<>, |
| 240 |
btrfs\-rescue(8) \%<> |
| 241 |
.\" End of generated man page. |