info > numfmt

man perldoc info pydoc3 ri search

🔢 numfmt: Reformat Numbers

📖 numfmt reads numbers in various representations and reformats them as requested. The most common usage is converting numbers to/from human representation (e.g. 4G ↦ 4,000,000,000).

numfmt [OPTION]... [NUMBER]

📌 numfmt converts each NUMBER on the command-line according to the specified options. If no NUMBERs are given, it reads numbers from standard input. numfmt can optionally extract numbers from specific columns, maintaining proper line padding and alignment.

✅ An exit status of zero indicates success, and a nonzero value indicates failure. See --invalid for additional information regarding exit status.

🚀 Quick Reference

Use Case	Command	Description
🔢 Convert to SI (human-readable)	numfmt --to=si 500000	Converts 500000 → 500K
🔢 Convert to IEC (binary)	numfmt --to=iec 500000	Converts 500000 → 489K
🔢 Convert from SI	numfmt --from=si 1M	Converts 1M → 1000000
🔢 Convert from IEC	numfmt --from=iec 1M	Converts 1M → 1048576
🔢 Auto-detect SI/IEC input	numfmt --from=auto 1Mi	Interprets Mi as Mebi (1048576)
📂 Convert specific field from pipe	ls -log | numfmt --field 3 --header --to=si	Converts file sizes (field 3) to SI
📊 Convert with padding	du -s * | numfmt --to=si --padding=10	Right-aligns output to 10 characters
📊 Group digits with locale	numfmt --from=iec --grouping 2G	Outputs 2,147,483,648 (in en_US)
📏 Custom unit size	numfmt --from-unit=512 10	Input 10 represents 10 units of 512 bytes
🏷️ Add suffix	numfmt --to=si --suffix=B 1M	Outputs 1MB

⚙️ General Options

🔍 Debugging

--debug — Print (to standard error) warning messages about possible erroneous usage.

🔤 Input/Output Formatting

• -d D, --delimiter=D — Use character D as input field separator (default: whitespace). ⚠️ Note: Using non-default delimiter turns off automatic padding.
• --field=FIELDS — Convert the number in input field FIELDS (default: 1). Supports cut style field ranges:
  • 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
• --format=FORMAT — Use printf-style floating FORMAT string. Must contain one %f directive, optionally with ', -, 0, width or precision modifiers. The ' modifier enables --grouping, - enables left-aligned --padding, width enables right-aligned --padding. 0 width modifier generates leading zeros. Precision like %.1f overrides auto-scaling precision.
• --grouping — Group digits in output numbers according to the current locale's grouping rules (e.g. thousands separator). No effect in POSIX/C locale.
• --header[=N] — Print the first N (default: 1) lines without any conversion.
• --padding=N — Pad output numbers to N characters by adding spaces. Positive N = right-aligned, negative N = left-aligned. Default: automatic alignment based on input line width (only with default delimiter).
• --suffix=SUFFIX — Add SUFFIX to output numbers, and accept optional SUFFIX in input numbers.
• -z, --zero-terminated — Delimit items with a zero byte (ASCII NUL) rather than newline. Useful with perl -0, find -print0, xargs -0. Note: with -z, newline is treated as a field separator.

📐 Scaling & Units

• --from=UNIT — Auto-scale input numbers according to UNIT. Default: no scaling (suffixes trigger error).
• --from-unit=N — Specify input unit size (default: 1). Use when input represents other units (e.g. --from-unit=512 for 512-byte blocks). Suffixes handled as with --from=auto.
• --to=UNIT — Auto-scale output numbers according to UNIT. Default: no scaling (all digits printed).
• --to-unit=N — Specify output unit size (default: 1). E.g. --to=si --to-unit=1000 for 1KB blocks. Suffixes handled as with --from=auto.

🔄 Rounding

--round=METHOD — Round numbers according to METHOD: up, down, from-zero (default), towards-zero, nearest.

⚠️ Error Handling

--invalid=MODE — Action on input errors:

• abort (default) — Exit immediately with status 2
• fail — Print warning for each error, exit with status 2
• warn — Print warning, exit with status 0
• ignore — No diagnostics, exit with status 0

📏 Possible UNITs

The following UNIT options are available with --from=UNITS and --to=UNITS:

🚫 NONE

No scaling performed. No suffixes accepted for input. All digits printed for output.

📐 SI (International System)

Auto-scale according to SI standard. Input accepts suffixes; output values >1000 rounded with suffix:

• K → 1000¹ = 10³ (Kilo)
• M → 1000² = 10⁶ (Mega)
• G → 1000³ = 10⁹ (Giga)
• T → 1000⁴ = 10¹² (Tera)
• P → 1000⁵ = 10¹⁵ (Peta)
• E → 1000⁶ = 10¹⁸ (Exa)
• Z → 1000⁷ = 10²¹ (Zetta)
• Y → 1000⁸ = 10²⁴ (Yotta)

💾 IEC (International Electrotechnical Commission, single letter)

Auto-scale according to IEC standard. Values >1024 rounded with suffix (single letter, non-standard but common):

• K → 1024¹ = 2¹⁰ (Kibi)
• M → 1024² = 2²⁰ (Mebi)
• G → 1024³ = 2³⁰ (Gibi)
• T → 1024⁴ = 2⁴⁰ (Tebi)
• P → 1024⁵ = 2⁵⁰ (Pebi)
• E → 1024⁶ = 2⁶⁰ (Exbi)
• Z → 1024⁷ = 2⁷⁰ (Zebi)
• Y → 1024⁸ = 2⁸⁰ (Yobi)

🔤 IEC-I (International Electrotechnical Commission, two-letter standard)

Auto-scale according to IEC standard. Values >1024 rounded with suffix (two-letter, standard compliant):

• Ki → 1024¹ = 2¹⁰ (Kibi)
• Mi → 1024² = 2²⁰ (Mebi)
• Gi → 1024³ = 2³⁰ (Gibi)
• Ti → 1024⁴ = 2⁴⁰ (Tebi)
• Pi → 1024⁵ = 2⁵⁰ (Pebi)
• Ei → 1024⁶ = 2⁶⁰ (Exbi)
• Zi → 1024⁷ = 2⁷⁰ (Zebi)
• Yi → 1024⁸ = 2⁸⁰ (Yobi)

🤖 AUTO

Only usable with --from. Numbers with K,M,G,T,P,E,Z,Y suffixes interpreted as SI values; numbers with Ki,Mi,Gi,Ti,Pi,Ei,Zi,Yi suffixes interpreted as IEC values.

💡 Examples of using numfmt

🔢 Converting a single number from/to human representation

$ numfmt --to=si 500000
500K

$ numfmt --to=iec 500000
489K

$ numfmt --to=iec-i 500000
489Ki

$ numfmt --from=si 1M
1000000

$ numfmt --from=iec 1M
1048576

# with '--from=auto', M=Mega, Mi=Mebi
$ numfmt --from=auto 1M
1000000
$ numfmt --from=auto 1Mi
1048576

🔄 Converting from SI to IEC scales

📌 E.g. when a harddisk capacity is advertised as 1TB, but the drive's capacity gives lower values:

$ numfmt --from=si --to=iec 1T
932G

📂 Converting a single field from piped input

📌 These examples are for demonstration purposes — both ls and df support --human-readable natively.

# Third field (file size) will be shown in SI representation
$ ls -log | numfmt --field 3 --header --to=si | head -n4
-rw-r--r--  1     94K Aug 23  2011 ABOUT-NLS
-rw-r--r--  1    3.7K Jan  7 16:15 AUTHORS
-rw-r--r--  1     36K Jun  1  2011 COPYING
-rw-r--r--  1       0 Jan  7 15:15 ChangeLog

# Second field (size) will be shown in IEC representation
$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
File system   1B-blocks        Used  Available Use% Mounted on
rootfs             132G   104741408   26554036  80% /
tmpfs              794M        7580     804960   1% /run/shm
/dev/sdb1          694G   651424756   46074696  94% /home

📐 Output padding and formatting

# Pad to 10 characters, right-aligned
$ du -s * | numfmt --to=si --padding=10
       2.5K config.log
        108 config.status
       1.7K configure
         20 configure.ac

# Pad to 10 characters, left-aligned
$ du -s * | numfmt --to=si --padding=-10
2.5K       config.log
108        config.status
1.7K       configure
20         configure.ac

# Pad to 10 characters, left-aligned, using 'format'
$ du -s * | numfmt --to=si --format="%10f"
       2.5K config.log
        108 config.status
       1.7K configure
         20 configure.ac

# Pad to 10 characters, left-aligned, using 'format'
$ du -s * | numfmt --to=si --padding="%-10f"
2.5K       config.log
108        config.status
1.7K       configure
20         configure.ac

🌍 Locale-aware grouping

$ LC_ALL=C numfmt --from=iec --grouping 2G
2147483648

$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
2,147,483,648

$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
2,14,74,83,648

$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G
==     2147483648==

$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G
==  2,147,483,648==

$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G
==2,147,483,648  ==

$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G
== 2,14,74,83,648==

🚪 Exit Codes

• ✅ 0 — Success
• ❌ 2 — Error (invalid input, conversion error, etc.)

🔢 numfmt: Reformat Numbers 🚀 Quick Reference ⚙️ General Options 📏 Possible UNITs 💡 Examples of using numfmt 🚪 Exit Codes