1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.50.1.
.TH NUMFMT "1" "February 2026" "GNU coreutils 9.10" "User Commands"
.\" Define monospaced roman font for groff in troff mode.
.if t .if \n(.g \{\
. ds mono \f(CR
. ds /mono \fP
.\}
.SH NAME
numfmt \- Convert numbers from/to human-readable strings
.SH SYNOPSIS
.B numfmt
[\fI\,OPTION\/\fR]... [\fI\,NUMBER\/\fR]...
.SH DESCRIPTION
.\" Add any additional description here
.PP
Reformat NUMBER(s), or the numbers from standard input if none are specified.
.PP
Mandatory arguments to long options are mandatory for short options too.
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--debug'\fB\-\-debug\fP\X'tty: link'
print warnings about invalid input
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt-d'\fB\-d, \-\-delimiter=\,X\fP\X'tty: link'\/\fR
use X instead of whitespace for field delimiter
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--field'\fB\-\-field=FIELDS\fP\X'tty: link'
replace the numbers in these input fields (default=1);
see FIELDS below for details
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--format'\fB\-\-format=FORMAT\fP\X'tty: link'
use printf style floating\-point FORMAT;
see FORMAT below for details
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--from'\fB\-\-from=UNIT\fP\X'tty: link'
auto\-scale input numbers to UNITs; default is 'none';
see UNIT below for details
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--from-unit'\fB\-\-from\-unit=N\fP\X'tty: link'
specify the input unit size (instead of the default 1)
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--grouping'\fB\-\-grouping\fP\X'tty: link'
use locale\-defined grouping of digits, e.g. 1,000,000.
This has no effect in the C/POSIX locale
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--header'\fB\-\-header[=N]\fP\X'tty: link'
print (without converting) the first N header lines;
N defaults to 1 if not specified
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--invalid'\fB\-\-invalid=MODE\fP\X'tty: link'
failure mode for invalid numbers;
MODE can be: abort (default), fail, warn, ignore
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--padding'\fB\-\-padding=N\fP\X'tty: link'
pad the output to N characters;
positive N will right\-align, negative N will left\-align;
padding is ignored if the output is wider than N;
the default is to automatically pad if a whitespace is found
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--round'\fB\-\-round=METHOD\fP\X'tty: link'
use METHOD for rounding when scaling; METHOD can be:
up, down, from\-zero (default), towards\-zero, nearest
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--suffix'\fB\-\-suffix=SUFFIX\fP\X'tty: link'
add SUFFIX to output numbers,
and accept an optional SUFFIX in input numbers
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--unit-separator'\fB\-\-unit\-separator=SEP\fP\X'tty: link'
insert SEP between number and unit on output,
and accept an optional SEP in input numbers
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--to'\fB\-\-to=UNIT\fP\X'tty: link'
auto\-scale output numbers to UNITs; see UNIT below
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt--to-unit'\fB\-\-to\-unit=N\fP\X'tty: link'
the output unit size (instead of the default 1)
.TP
\X'tty: link https://www.gnu.org/software/coreutils/manual/coreutils.html#numfmt-z'\fB\-z, \-\-zero\-terminated\fP\X'tty: link'
line delimiter is NUL, not newline
.TP
\X'tty: link https://www.gnu.org/software/coreutils/numfmt#numfmt--help'\fB\-\-help\fP\X'tty: link'
display this help and exit
.TP
\X'tty: link https://www.gnu.org/software/coreutils/numfmt#numfmt--version'\fB\-\-version\fP\X'tty: link'
output version information and exit
.SS "UNIT options:"
.TP
none
no auto\-scaling is done; suffixes will trigger an error
.TP
auto
accept optional single/two letter suffix:
1K = 1000, 1k = 1000,
1Ki = 1024,
1M = 1000000,
1Mi = 1048576,
.TP
si
accept optional single letter suffix:
1k = 1000, 1K = 1000,
1M = 1000000,
\&...
.TP
iec
accept optional single letter suffix:
1K = 1024, 1k = 1024,
1M = 1048576,
\&...
.TP
iec\-i
accept optional two\-letter suffix:
1Ki = 1024, 1ki = 1024,
1Mi = 1048576,
\&...
.SS "FIELDS supports \fBcut\fP(1) style field ranges:"
.TP
N
N'th field, counted from 1
.TP
N\-
from N'th field, to end of line
.TP
N\-M
from N'th to M'th field (inclusive)
.TP
\fB\-M\fR
from first to M'th field (inclusive)
.TP
\-
all fields
.PP
Multiple fields/ranges can be separated with commas
.PP
FORMAT must be suitable for printing one floating\-point argument '%f'.
Optional quote (%'f) will enable \fB\-\-grouping\fR (if supported by current locale).
Optional width value (%10f) will pad output. Optional zero (%010f) width
will zero pad the number. Optional negative values (%\-10f) will left align.
Optional precision (%.1f) will override the input determined precision.
.PP
Exit status is 0 if all input numbers were successfully converted.
By default, numfmt will stop at the first conversion error with exit status 2.
With \fB\-\-invalid\fR=\fI\,'fail'\/\fR a warning is printed for each conversion error
and the exit status is 2. With \fB\-\-invalid\fR=\fI\,'warn'\/\fR each conversion error is
diagnosed, but the exit status is 0. With \fB\-\-invalid\fR=\fI\,'ignore'\/\fR conversion
errors are not diagnosed and the exit status is 0.
.SH EXAMPLES
.IP
\*[mono]$ numfmt --to=si 1000\*[/mono]
.IP
\-> "1.0k"
.IP
\*[mono]$ numfmt --to=iec 2048\*[/mono]
.IP
\-> "2.0K"
.IP
\*[mono]$ numfmt --to=iec-i 4096\*[/mono]
.IP
\-> "4.0Ki"
.IP
\*[mono]$ echo 1K | numfmt --from=si\*[/mono]
.IP
\-> "1000"
.IP
\*[mono]$ echo 1K | numfmt --from=iec\*[/mono]
.IP
\-> "1024"
.IP
\*[mono]$ df -B1 | numfmt --header --field 2-4 --to=si\*[/mono]
.br
\*[mono]$ ls -l | numfmt --header --field 5 --to=iec\*[/mono]
.br
\*[mono]$ ls -lh | numfmt --header --field 5 --from=iec --padding=10\*[/mono]
.br
\*[mono]$ ls -lh | numfmt --header --field 5 --from=iec --format %10f\*[/mono]
.SH AUTHOR
Written by Assaf Gordon.
.SH "REPORTING BUGS"
Report bugs to: bug\-coreutils@gnu.org
.br
GNU coreutils home page: <https://www.gnu.org/software/coreutils/>
.br
General help using GNU software: <https://www.gnu.org/gethelp/>
.br
Report any translation bugs to <https://translationproject.org/team/>
.SH COPYRIGHT
Copyright \(co 2026 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "SEE ALSO"
Full documentation <https://www.gnu.org/software/coreutils/numfmt>
.br
or available locally via: info \(aq(coreutils) numfmt invocation\(aq
|
