NUMFMT(1)

📦
version 9.10 · 5 versions
, in ubuntu stonking

🎀 NAME 🎀

numfmt — the glow-up your numbers have been waiting for: convert numbers from/to human-readable strings 💅✨

🦋 SYNOPSIS 🦋

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

🌸 DESCRIPTION 🌸

Okay so picture this, bestie: numfmt reformats your NUMBER(s) — or, if you didn't hand it any numbers, it takes the numbers from standard input. Either way, it's giving ✨conversion era✨.

Real talk though: mandatory arguments to long options are mandatory for short options too. No sneaking around that one, fr fr. 🙈

  • --debug — prints warnings about invalid input 👀
  • -d, --delimiter=X — use X as the field delimiter instead of whitespace
  • --field=FIELDS — swap out the numbers in these input fields (default is 1); peep FIELDS below for the deets
  • --format=FORMAT — use a printf-style floating-point FORMAT; check FORMAT below for the details
  • --from=UNIT — auto-scale the input numbers to UNITs; default is none; see UNIT below, iykyk
  • --from-unit=N — specify the input unit size (instead of the default 1)
  • --grouping — use locale-defined grouping of digits, like 1,000,000. Okay but heads up: 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
  • --invalid=MODE — the failure mode for invalid numbers; MODE can be: abort (that's the default), fail, warn, ignore
  • --padding=N — pad the output to N characters; a positive N will right-align, a negative N will left-align; padding gets ignored if the output is already 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 bestie), towards-zero, nearest
  • --suffix=SUFFIX — add SUFFIX to the output numbers, and accept an optional SUFFIX on the input numbers
  • --unit-separator=SEP — insert SEP between the number and the unit on output, and accept an optional SEP in the input numbers
  • --to=UNIT — auto-scale the 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 at all; suffixes will trigger an error 😭
  • auto — accept an optional single/two letter suffix: 1K = 1000, 1k = 1000, 1Ki = 1024, 1M = 1000000, 1Mi = 1048576,
  • si — accept an optional single letter suffix: 1k = 1000, 1K = 1000, 1M = 1000000, ...
  • iec — accept an optional single letter suffix: 1K = 1024, 1k = 1024, 1M = 1048576, ...
  • iec-i — accept an optional two-letter suffix: 1Ki = 1024, 1ki = 1024, 1Mi = 1048576, ...

🌈 FIELDS supports cut(1) style field ranges 🌈

  • N — the N'th field, counted from 1
  • N- — from the N'th field, to the end of the line
  • N-M — from the N'th to the M'th field (inclusive)
  • -M — from the first to the M'th field (inclusive)
  • - — all fields, every single one, no crumbs left behind

Multiple fields/ranges can be separated with commas, because of course they can 💅

FORMAT must be suitable for printing one floating-point argument '%f'. The optional quote (%'f) will enable --grouping (if it's supported by your current locale). The optional width value (%10f) will pad the output. The optional zero (%010f) width will zero pad the number. Optional negative values (%-10f) will left align. And the optional precision (%.1f) will override the input determined precision. Slay. 🎀

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. Pick your fighter. 🔥

🔥 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. Respect the icon, no cap. 🙌

🐛 REPORTING BUGS 🐛

Found something cursed? Tell the devs, bestie:

💜 SEE ALSO 💜

  • Full documentation: https://www.gnu.org/software/coreutils/numfmt — or available locally via: info '(coreutils) numfmt invocation'
  • Packaged by Ubuntu (9.10-1ubuntu2)
  • 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. 🫣

and that's a wrap, bestie!! 🌈 this whole vibe check came to you courtesy of GNU coreutils 9.10, dated August 2026, and it's living in the NUMFMT(1) slot of your manual — go convert some numbers and be the main character of your own terminal. 💖⭐🦋

📦 where this page comes from