Python Humanize Utilities

4.15.0 · active · verified Wed Apr 08

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.

Common errors

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

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

pip install humanize Install latest version

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

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

view raw JSON →