humanize
Human-readable number, date, time, and file size formatting for Python — converts machine values to natural language. humanize features: naturaltime() for 'an hour ago' / 'in 3 minutes', naturalday() for 'yesterday' / 'today', naturaldate() for 'Jan 15', intcomma() for '1,234,567', intword() for '1.2 million', intpluralizer for 'N item(s)', ordinal() for '1st'/'2nd', filesize() / naturalsize() for '1.2 GB', scientific() for '1.23 × 10⁴', fraction(), ap_number(), and i18n locale support for dozens of languages.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Pure formatting library with no network calls. No security concerns. Formatting user-provided numbers: validate input types before passing to avoid TypeError. Output is display-only strings — no eval or execution risk.
⚡ Reliability
Best When
Displaying values to users in natural language — humanize is the go-to library for making machine numbers and dates readable in web UIs, CLIs, and reports.
Avoid When
Complex locale formatting (use babel), date parsing (use arrow/dateutil), or when format string control is sufficient.
Use Cases
- • Agent time display — import humanize; import datetime; diff = datetime.timedelta(hours=2, minutes=30); print(humanize.naturaltime(diff)) — '2 hours ago'; past = datetime.datetime.now() - datetime.timedelta(days=3); print(humanize.naturaltime(past)) — '3 days ago'; agent displays timestamps in human-readable relative format
- • Agent number formatting — print(humanize.intcomma(1234567)) — '1,234,567'; print(humanize.intword(1200000)) — '1.2 million'; print(humanize.ordinal(23)) — '23rd'; agent formats large numbers for display; intword supports up to 'decillion'; ordinal handles 1st/2nd/3rd/4th+ correctly
- • Agent file size display — print(humanize.naturalsize(1073741824)) — '1.1 GB'; print(humanize.naturalsize(1073741824, binary=True)) — '1.0 GiB'; print(humanize.naturalsize(500)) — '500 Bytes'; agent displays file sizes in human-friendly format; binary=True for GiB/MiB/KiB; default is SI (GB/MB/KB)
- • Agent localized output — import humanize; humanize.activate('de_DE'); print(humanize.intcomma(1234567)) — '1.234.567'; print(humanize.naturaltime(datetime.timedelta(hours=1))) — 'vor einer Stunde'; humanize.deactivate() — i18n; agent displays in user's locale; supports 50+ languages; activate() sets thread-local locale
- • Agent pluralization — print(humanize.pluralize(1, 'item')) — '1 item'; print(humanize.pluralize(5, 'item')) — '5 items'; print(humanize.apnumber(5)) — 'five'; agent handles singular/plural correctly; apnumber converts 1-9 to words per AP style guide
Not For
- • Locale-specific number formatting — humanize has basic i18n; for full locale formatting use babel or locale module
- • Date parsing — humanize formats dates but doesn't parse; for parsing use arrow or python-dateutil
- • Precise number formatting control — for exact decimal places and format control use Python's format() or babel
Interface
Authentication
No auth — formatting utility library.
Pricing
humanize is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ naturaltime() is relative to now — humanize.naturaltime(some_datetime) computes relative to datetime.now(); agent code testing: mock datetime.now() or use timedelta: naturaltime(timedelta(hours=2)) — '2 hours ago'; naturaltime() with future timedelta: naturaltime(timedelta(hours=-2)) — 'in 2 hours'; sign of timedelta determines past/future
- ⚠ activate() is thread-local — humanize.activate('fr_FR') sets locale for current thread only; agent code using threads must call activate() per thread; in async code: activate() is coroutine-unsafe (single event loop thread); set locale once at startup for single-locale apps
- ⚠ naturalsize() base-10 vs base-2 — naturalsize(1000) — '1.0 kB' (SI, base-10); naturalsize(1024) — '1.0 kB' (not 1 KiB); for binary: naturalsize(1024, binary=True) — '1.0 KiB'; agent code for disk space: use binary=True; for network bandwidth: use default SI; different from Windows Explorer vs Linux df
- ⚠ intword() max is 'decillion' — humanize.intword(10**33) — '1.0 decillion'; larger numbers fall back to scientific notation; agent code with astronomical numbers: use scientific() or format with intcomma(); intword is designed for readable display not scientific precision
- ⚠ Locale files may not be installed — humanize.activate('zh_CN') requires Chinese locale data; if not installed raises FileNotFoundError or returns English fallback; agent code: test locale availability; use try/except humanize.activate(); default to 'en_US' as fallback
- ⚠ naturalday() is date-only not datetime — humanize.naturalday(datetime.date.today()) — 'today'; humanize.naturalday(datetime.datetime.now()) converts to date; agent code: naturalday() for calendar dates; naturaltime() for specific times; combining: f'{naturaltime(dt)} ({naturalday(dt)})' for full context
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for humanize.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.