Scroll to navigation

NUMFMT(1) User Commands NUMFMT(1)

NAME

numfmt - Convert numbers from/to human-readable strings

SYNOPSIS

numfmt [OPTION]... [NUMBER]...

DESCRIPTION

Reformat NUMBER(s), or the numbers from standard input if none are specified.

Mandatory arguments to long options are mandatory for short options too.

print warnings about invalid input
use X instead of whitespace for field delimiter
replace the numbers in these input fields (default=1); see FIELDS below for details
use printf style floating-point FORMAT; see FORMAT below for details
auto-scale input numbers to UNITs; default is 'none'; see UNIT below for details
specify the input unit size (instead of the default 1)
use locale-defined grouping of digits, e.g. 1,000,000. This has no effect in the C/POSIX locale
print (without converting) the first N header lines; N defaults to 1 if not specified
failure mode for invalid numbers; MODE can be: abort (default), fail, warn, ignore
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
use METHOD for rounding when scaling; METHOD can be: up, down, from-zero (default), towards-zero, nearest
add SUFFIX to output numbers, and accept an optional SUFFIX in input numbers
insert SEP between number and unit on output, and accept an optional SEP in input numbers
auto-scale output numbers to UNITs; see UNIT below
the output unit size (instead of the default 1)
line delimiter is NUL, not newline
display this help and exit
output version information and exit

UNIT options:

no auto-scaling is done; suffixes will trigger an error
accept optional single/two letter suffix: 1K = 1000, 1k = 1000, 1Ki = 1024, 1M = 1000000, 1Mi = 1048576,
accept optional single letter suffix: 1k = 1000, 1K = 1000, 1M = 1000000, ...
accept optional single letter suffix: 1K = 1024, 1k = 1024, 1M = 1048576, ...
iec-i
accept optional two-letter suffix: 1Ki = 1024, 1ki = 1024, 1Mi = 1048576, ...

FIELDS supports cut(1) style field ranges:

N'th field, counted from 1
N-
from N'th field, to end of line
N-M
from N'th to M'th field (inclusive)
from first to M'th field (inclusive)
-
all fields

Multiple fields/ranges can be separated with commas

FORMAT must be suitable for printing one floating-point argument '%f'. Optional quote (%'f) will enable --grouping (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.

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 --invalid='fail' a warning is printed for each conversion error and the exit status is 2. With --invalid='warn' each conversion error is diagnosed, but the exit status is 0. With --invalid='ignore' conversion errors are not diagnosed and the exit status is 0.

EXAMPLES

$ numfmt --to=si 1000
-> "1.0k"
$ numfmt --to=iec 2048
-> "2.0K"
$ numfmt --to=iec-i 4096
-> "4.0Ki"
$ echo 1K | numfmt --from=si
-> "1000"
$ echo 1K | numfmt --from=iec
-> "1024"
$ df -B1 | numfmt --header --field 2-4 --to=si
$ ls -l | numfmt --header --field 5 --to=iec
$ ls -lh | numfmt --header --field 5 --from=iec --padding=10
$ ls -lh | numfmt --header --field 5 --from=iec --format %10f

AUTHOR

Written by Assaf Gordon.

REPORTING BUGS

Report bugs to: bug-coreutils@gnu.org
GNU coreutils home page: <https://www.gnu.org/software/coreutils/>
General help using GNU software: <https://www.gnu.org/gethelp/>
Report any translation bugs to <https://translationproject.org/team/>

SEE ALSO

Full documentation <https://www.gnu.org/software/coreutils/numfmt>
or available locally via: info '(coreutils) numfmt invocation'

Packaged by Debian (9.10-1)
Copyright © 2026 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

February 2026 GNU coreutils 9.10