NUMFMT(1)

📦
version 9.12 · 23 versions
, in arch rolling

✨ NUMFMT 💅 the number glow-up machine ✨

okay bestie, so this is numfmt, and she lives in the User Commands part of the manual (section 1). If you've ever stared at 1048576 and thought "girl, what is that in vibes" — this is the page for you. 🫶

🎀 NAME 🎀

numfmt — Convert numbers from/to human-readable strings

🦋 SYNOPSIS 🦋

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

🌸 DESCRIPTION 🌸

Reformat NUMBER(s) — or, if you didn't hand her any numbers, the numbers coming in from standard input. She'll take them and give them the glow-up. ✨

Mandatory arguments to long options are mandatory for short options too. (yes bestie, that rule is universal, no exceptions, periodt.)

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

👑 UNIT options 👑

  • none — no auto-scaling is done; suffixes will trigger an error 🚨
  • auto — accept optional single/two letter suffix: 1K = 1000, 1k = 1000, 1Ki = 1024, 1M = 1000000, 1Mi = 1048576,
  • si — accept optional single letter suffix: 1k = 1000, 1K = 1000, 1M = 1000000, ...
  • iec — 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 🧚

okay so FIELDS supports cut(1) style field ranges, and honestly? iconic behaviour:

  • N — 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)
  • -M — from first to M'th field (inclusive)
  • - — all fields
  • Multiple fields/ranges can be separated with commas

🍓 FORMAT 🍓

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, bestie 💀

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.
not her being forgiving in warn and ignore mode 😭 she really said "no stress, we move on."

🌈 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. (shoutout 🫡)

🚨 REPORTING BUGS 🚨

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

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.

that "NO WARRANTY" is in all caps for a reason bestie, do not come for her if something breaks 🙈

👀 SEE ALSO 👀

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

and that's the whole page, no cap. this was GNU coreutils 9.12, from September 2026 — she's serving section 1 of the User Commands manual and she ate 💅✨

📦 where this page comes from