Registry / data / humanize

humanize

JSON →
library4.16.0pypypi✓ verified 25d ago

humanize is a Python library (current version 4.15.0) that provides a collection of utilities to make data more human-readable. It transforms raw numerical values, dates, times, and file sizes into intuitive and easily understandable formats, bridging the gap between machine-centric data and human comprehension. The project maintains an active release cadence, with frequent updates and a focus on expanding localization support.

pip install humanize
INSTALL
IMPORT
SIG · HUMANIZE
H
humanize
datapythonv4.16.0
Install
1.7s avg
Import
10ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 18.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.7s · import 0.010s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

humanize
import humanize
intcomma
from humanize import intcomma
For direct access to specific formatting functions.
naturalsize
from humanize import naturalsize
For direct access to specific formatting functions.

This quickstart demonstrates common `humanize` functionalities, including formatting numbers with commas or words, converting numbers to ordinals, presenting dates and times in natural language, and converting byte counts into human-readable file sizes.

import humanize import datetime as dt # Humanize numbers print(f"Commas: {humanize.intcomma(1234567)}") print(f"Words: {humanize.intword(1234567890)}") print(f"Ordinal: {humanize.ordinal(21)}") # Humanize dates and times now = dt.datetime.now() one_hour_ago = now - dt.timedelta(hours=1, minutes=5) tomorrow = now + dt.timedelta(days=1) print(f"Time ago: {humanize.naturaltime(one_hour_ago)}") print(f"Time from now: {humanize.naturaltime(tomorrow, future=True)}") print(f"Natural day: {humanize.naturalday(now)}") # Humanize file sizes print(f"File size: {humanize.naturalsize(1024 * 1024 * 1.5)}")
Debug
Known issues
breakingPython 3.9 support was dropped in humanize version 4.14.0. Users running Python 3.9 or older environments must either upgrade their Python version or pin humanize to a version less than 4.14.0.
fix
Upgrade Python to 3.10 or newer, or pin `humanize < 4.14.0` in your dependencies.
affects: >=4.14.0
breakingPython 3.8 support was dropped in humanize version 4.11.0. Users running Python 3.8 or older environments must either upgrade their Python version or pin humanize to a version less than 4.11.0.
fix
Upgrade Python to 3.10 or newer, or pin `humanize < 4.11.0` in your dependencies.
affects: >=4.11.0
gotcha`naturaldelta` in versions prior to 4.13.0 had rounding issues that could lead to less precise human-readable duration strings.
fix
Upgrade to humanize 4.13.0 or a newer version to benefit from improved rounding and precision in `naturaldelta`.
affects: <4.13.0
gotchaVersions 4.12.0 and 4.12.1 introduced regressions where `naturalsize` could incorrectly format float inputs.
fix
Upgrade to humanize 4.12.3 or a newer version to resolve the `naturalsize` float input regression.
affects: 4.12.0 - 4.12.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'humanize'
The 'humanize' package has not been installed in your Python environment, or the Python interpreter you are using does not have access to the installed package.
fix
Install the package using pip: `pip install humanize`
TypeError: can't subtract offset-naive and offset-aware datetimes
The `humanize.naturaltime` function is being called with a timezone-aware datetime object, but it's being compared internally with a timezone-naive `datetime.now()`, leading to a type mismatch.
fix
Ensure both datetime objects are either consistently timezone-naive or timezone-aware and in the same timezone. You can explicitly provide a timezone-aware reference point using the `when` parameter in `naturaltime`. 
```python
import datetime
import humanize

# Example: Convert to UTC if the original datetime is timezone-aware
aware_dt = datetime.datetime.now(datetime.timezone.utc)
print(humanize.naturaltime(aware_dt, when=datetime.datetime.now(datetime.timezone.utc)))

# Example: Make the input datetime naive if local time comparison is intended
naive_dt = datetime.datetime.now().replace(tzinfo=None)
print(humanize.naturaltime(naive_dt))
```
AttributeError: module 'humanize' has no attribute 'precisedelta'
You are attempting to use a function (like `precisedelta`) that either does not exist in the version of `humanize` currently installed, was deprecated, or the function name is misspelled. `precisedelta` was introduced in a later version, so an older installed version might not have it.
fix
First, ensure the function name is spelled correctly. If it is, upgrade the `humanize` library to its latest version: `pip install --upgrade humanize`. Then consult the official documentation for the correct usage.
FileNotFoundError: [Errno 2] No translation file found for domain: 'humanize'
This error occurs when `humanize.i18n.activate()` is called with a locale that does not have corresponding translation files, or the specified `path` to translation files is incorrect or inaccessible.
fix
Ensure the locale string is correct (e.g., 'es_ES', 'fr_FR') and that the necessary translation files for `humanize` exist and are accessible at the specified path (if provided). If using a standard locale, ensure `humanize` is correctly installed, as it ships with its own translations. 
```python
import humanize

# Example with a supported locale
try:
    humanize.i18n.activate('es_ES')
    print(humanize.naturalday(datetime.date.today()))
except FileNotFoundError as e:
    print(f"Translation error: {e}. Check if 'es_ES' translations are available or path is correct.")
```
Upgrade
Version history
4.16.0latest on PyPI · released Jun 30, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
12
Resources
humanize — pip install humanize · libregistry