Python Humanize Utilities

4.15.0 verified Tue May 12 auth: no python install: verified quickstart: verified

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

Common errors

error ModuleNotFoundError: No module named 'humanize' ↓

cause 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

error TypeError: can't subtract offset-naive and offset-aware datetimes ↓

cause 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.

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))

error AttributeError: module 'humanize' has no attribute 'precisedelta' ↓

cause 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.

error FileNotFoundError: [Errno 2] No translation file found for domain: 'humanize' ↓

cause 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.

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.")

Warnings

breaking Python 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.

breaking Python 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.

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`.

gotcha Versions 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 18.6M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) - - 0.01s 20.4M

3.11 slim (glibc) - - 0.01s 21M

3.12 alpine (musl) - - 0.01s 12.3M

3.12 slim (glibc) - - 0.01s 13M

3.13 alpine (musl) - - 0.01s 11.9M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) - - 0.01s 18.1M

3.9 slim (glibc) - - 0.01s 19M

Imports

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.

Quickstart verified last tested: 2026-04-23

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)}")