go-humanize

go-humanize is a small, dependency-free Go library that turns raw numeric and time values into the kind of strings people actually want to read — “83 MB” instead of 82854982, “3 weeks ago” instead of a raw timestamp, “1,234,567” instead of an unformatted integer. It groups its functions by concern: byte-size formatting (SI and IEC units, plus parsing back from a string), relative time formatting with a customizable magnitude table, comma-grouped integers and floats (including arbitrary-precision big.Int/big.Float support), ordinal suffixes, SI-prefix notation, and a small english subpackage for basic English pluralization and word-series joining.

The project has been stable for over a decade and is one of the most widely vendored Go utility packages in the ecosystem, used by tools like Docker, Kubernetes, and Terraform for exactly the kind of human-facing number and time formatting that the Go standard library deliberately leaves out.

What You Get

• SI and IEC byte-size formatting (Bytes, IBytes, and digit-limited BytesN/IBytesN variants) plus ParseBytes to go back from a string like “42 MB” to a uint64
• Relative time formatting (Time, RelTime, CustomRelTime) with a fully overridable magnitude/format table for custom thresholds and wording
• Comma-grouped number formatting for int64, float64, and arbitrary-precision big.Int/big.Float values
• Ordinal suffix formatting (Ordinal(193) -> “193rd”) and SI-prefix formatting/parsing (SI, ComputeSI, ParseSI) across the full quecto-to-quetta prefix range
• A humanize/english subpackage for regular-and-common-irregular English pluralization and comma/conjunction word-series joining

Common Use Cases

• Showing upload/download sizes, disk usage, or file sizes in CLI tools and dashboards
• Rendering “created 3 days ago” / “updated 2 hours ago” style timestamps in web UIs and API responses
• Formatting large counts (bytes transferred, row counts, currency-like figures) with thousands separators in logs or reports
• Building CLI or API output that pluralizes counts correctly (“1 object” vs “42 objects”) without hand-rolled pluralization logic

Under The Hood

Architecture go-humanize is organized as a single flat humanize package with one function-per-concern file (bytes.go, times.go, comma.go, si.go, ordinals.go, number.go, big.go, ftoa.go) plus a separate humanize/english subpackage for pluralization and word-series joining, which itself imports the root package for its Comma helper. There is no internal layering, dependency injection, or shared mutable state beyond a few package-level lookup tables and a compiled regex built once in an init() for SI parsing — each formatter is an independent, side-effect-free function, which keeps the blast radius of any single change narrow but also means the package offers no extensibility beyond the RelTimeMagnitude table exposed for CustomRelTime.

Tech Stack The module (go.mod, go 1.16) has zero external dependencies — every function is built from the Go standard library alone (fmt, math, math/big, strconv, strings, unicode, time, sort, regexp, errors, bytes). CI runs on GitHub Actions, building with go build ./... and testing with go test ./... against a pinned Go toolchain version. There is no build step beyond the standard Go toolchain and no runtime deployment target, since it’s a library rather than a service.

Code Quality Every source file has a matching _test.go counterpart, including a dedicated fuzz test for comma formatting (comma_fuzz_test.go), and CI runs the full suite with go test -v ./... on every push and pull request. Error handling is explicit where inputs can be malformed — ParseBytes and ParseSI return a Go error rather than panicking — though FormatFloat panics on malformed format-directive strings, which is a sharp edge for callers passing user-supplied format strings. Naming follows idiomatic Go conventions (exported PascalCase functions with runnable-example doc comments), and no dedicated linter configuration is present, though the small, single-purpose functions leave little surface for style drift.

API Design The library is deliberately zero-configuration: importing humanize and calling a single function like humanize.Bytes(n) or humanize.Time(t) is the entire integration, with every exported function documented via a doc comment that includes a literal input/output example. The english subpackage is kept separate rather than folded into the root package, avoiding namespace bloat for functionality most callers won’t need. The one API wrinkle is FormatFloat’s custom "#,###.##"-style format-string syntax, which is more expressive but less discoverable than the rest of the package’s plain function calls.