LinuxCommandLibrary

numfmt

Format numbers to human-readable strings

TLDR

Convert 1.5K (SI Units) to 1500

$ numfmt --from si 1.5K
copy

Convert 5th field (1-indexed) to IEC Units without converting header
$ ls -l | numfmt --header=1 --field 5 --to iec
copy

Convert to IEC units, pad with 5 characters, left aligned
$ du [[-s|--summarize]] * | numfmt --to iec --format "%-5f"
copy

SYNOPSIS

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

PARAMETERS

--from=UNIT
    Specify the input unit for numbers. Common units include auto (detects common suffixes), si (powers of 1000, e.g., 'K' for 1000), or iec-bytes (powers of 1024, e.g., 'K' for 1024).

--to=UNIT
    Specify the output unit for numbers. Similar to --from, allows conversion to different scales and unit systems.

-d, --delimiter=DELIM
    Use DELIM as the field delimiter for input and output, instead of the default whitespace.

-f, --fields=FIELDS
    Select specific fields (columns) to convert. Fields can be a comma-separated list or a range (e.g., '1,3-5' or '2-').

--format=FORMAT
    Use a printf-style FORMAT string for the output number (e.g., '%.2f' for two decimal places, or '%' to add a percentage sign).

--round=METHOD
    Specify the rounding method to use. Options include up (round towards positive infinity), down (round towards negative infinity), nearest (round to nearest, ties to even), and from-zero (round away from zero).

--suffix=SUFFIX
    Append a SUFFIX to the end of each converted number in the output.

--invalid=METHOD
    Define behavior for invalid numbers encountered in input. Methods include fail (exit with error), warn (print warning), ignore (skip conversion), or abort (exit immediately).

-H, --header
    Treat the first line of input as a header and skip its conversion, passing it through unchanged.

DESCRIPTION

numfmt is a GNU Coreutils command-line utility designed for formatting and converting numbers between various human-readable formats and raw numerical values. It's particularly useful when dealing with file sizes, memory quantities, or other large numbers that are often expressed with suffixes like 'K', 'M', 'G' (for kilobytes, megabytes, gigabytes).

The command can interpret numbers with these suffixes (e.g., '1.5G') and convert them into their byte equivalent, or vice-versa. It supports both SI units (powers of 1000) and IEC binary units (powers of 1024), allowing precise control over how numbers are interpreted and displayed.

numfmt excels in scripting contexts, allowing developers and system administrators to process numerical data from command outputs or log files, ensuring consistent formatting for display or further calculations. It provides options for specifying input/output units, field selection, rounding methods, and custom output formatting.

CAVEATS

numfmt primarily operates on numbers expressed with standard SI or IEC binary prefixes. It may not handle arbitrary complex numerical expressions or scientific notation outside of these contexts without specific formatting.

The default interpretation for units is IEC binary (powers of 1024) for input and output, which can sometimes lead to confusion if SI units (powers of 1000) are expected and not explicitly specified with --from=si or --to=si. Always be mindful of the unit system being used.

TYPICAL USE CASES

numfmt is frequently used by system administrators and developers to:

  • Convert output from commands like ls -lh or df -h (which use human-readable formats) into raw bytes for calculations or sorting.
  • Format raw byte counts into human-readable sizes (e.g., '1048576' to '1M').
  • Process logs or data files where numerical values are embedded with various unit suffixes to normalize the data.

UNIT INTERPRETATION

By default, numfmt uses IEC binary prefixes (Ki, Mi, Gi representing powers of 1024). This is common in computing for memory and disk sizes.

To use standard SI decimal prefixes (K, M, G representing powers of 1000), which are more common in general measurements and some networking contexts, the --from=si or --to=si option must be explicitly used. Understanding this distinction is crucial for accurate and expected conversions.

HISTORY

numfmt is a relatively modern addition to the GNU Coreutils package, which provides essential command-line utilities for Linux and other Unix-like operating systems. It was introduced to standardize and simplify the conversion of human-readable numbers, particularly sizes, making it easier to script and automate tasks involving such data. Its development aligns with the GNU project's goal of providing robust and flexible tools for system administration and data processing.

SEE ALSO

printf(1), awk(1), cut(1), sort(1), du(1), df(1)

Copied to clipboard