Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Using Python Humanize: naturaltime, naturaldate, and intcomma

Learn how to use Python's humanize library: naturaltime for relative times, naturaldate for calendar dates, and intcomma for number grouping.

~5 min readPython
#humanize#datetime formatting#number formatting#localization
A clock and a number with commas representing humanize's naturaltime, naturaldate, and intcomma formatting in Python.

The humanize library helps turn raw timestamps and numbers into strings people can read at a glance. naturaltime, naturaldate, and intcomma cover three common formatting needs: relative time, calendar dates, and numeric grouping. This article focuses on how to use them correctly, what their output looks like, and where their behavior can surprise you.

Installing and Importing humanize

The humanize package is available on PyPI and installs with pip:

bash
pip install humanize

Once installed, import the functions you need directly:

python
from humanize import naturaltime, naturaldate, intcomma

All three functions work with Python 3 and are pure Python, so they integrate easily into web applications, CLI tools, or data pipelines. The examples below assume a recent version of the library; behavior for edge cases may vary slightly across versions, so check the library's changelog if you depend on a specific output format.

Using naturaltime for Relative Time

naturaltime converts a datetime, date, timedelta, or numeric timestamp into a human-friendly relative phrase. The most common use is showing when an event occurred relative to now.

python
from datetime import datetime, timedelta from humanize import naturaltime now = datetime.now() print(naturaltime(now - timedelta(seconds=5))) # "5 seconds ago" print(naturaltime(now - timedelta(days=2))) # "2 days ago" print(naturaltime(now + timedelta(hours=3))) # "3 hours from now" print(naturaltime(now)) # "now"

The function chooses past or future phrasing based on the value you pass. For a timedelta, the library treats the value as a difference from now: a positive delta is interpreted as an offset in the past, so timedelta(days=1) produces "a day ago", while a negative delta produces a future phrase such as "a day from now". If you pass a datetime in the past, you get "... ago"; if it's in the future, you get "... from now".

If you need to compare against a fixed reference time instead of the moment the function is called, pass a datetime as the optional when argument:

python
reference = datetime(2025, 1, 1, 12, 0) print(naturaltime(datetime(2024, 12, 31, 12, 0), when=reference)) # "a day ago"

This can be useful in reports or loops where you want every row to use the same reference point.

Using naturaldate for Human-Readable Dates

naturaldate formats a date or datetime as a concise calendar date. It uses the current date as a reference and returns special phrases for today, yesterday, and tomorrow.

python
from datetime import date, timedelta from humanize import naturaldate today = date.today() print(naturaldate(today)) # "today" print(naturaldate(today - timedelta(days=1))) # "yesterday" print(naturaldate(today + timedelta(days=1))) # "tomorrow" print(naturaldate(today + timedelta(days=10))) # e.g. "Jan 5 2026"; depends on today

For dates further away, it falls back to a month-day-year format. The exact format depends on the locale and library version, but it typically follows the %b %d %Y pattern, for example Jan 5 2026.

Unlike naturaltime, naturaldate does not include the time of day. If you pass a datetime, it ignores the time component and only considers the date. This makes it suitable for showing deadlines, birthdays, or any calendar event where the time is irrelevant.

Using intcomma for Number Formatting

intcomma inserts thousands separators into integers and floats. For floats, it separates the integer part and leaves the fractional part unchanged.

python
from humanize import intcomma print(intcomma(1234567)) # "1,234,567" print(intcomma(1234567.891)) # "1,234,567.891" print(intcomma(-1000000)) # "-1,000,000" print(intcomma(100)) # "100"

The function works with both int and float types, and also with strings that represent numbers. For strings, it inserts commas into the digit groups:

python
print(intcomma("1234567")) # "1,234,567" print(intcomma("1234567.89")) # "1,234,567.89"

If you are processing user input or external data, it is best to convert values to a numeric type when you need predictable behavior. Numeric strings are convenient, but malformed input can produce results that are surprising or version-dependent.

Combining These Functions in Realistic Output

In practice, you rarely use these functions in isolation. A typical use case is generating a human-readable activity feed or a dashboard that shows both relative time and formatted numbers.

python
from datetime import datetime, timedelta from humanize import naturaltime, naturaldate, intcomma last_seen = datetime.now() - timedelta(hours=5) file_size = 8451234 print(f"Last seen: {naturaltime(last_seen)}") print(f"File size: {intcomma(file_size)} bytes") print(f"Report date: {naturaldate(last_seen.date())}")

Output:

text
Last seen: 5 hours ago File size: 8,451,234 bytes Report date: today

Because these functions return plain strings, you can embed them in templates, log messages, or API responses without extra formatting logic.

Localization and Language Support

The humanize library supports multiple locales. By default, it uses English, but you can activate a different locale to get localized output for all three functions.

python
import humanize from datetime import datetime, timedelta humanize.activate("fr_FR") now = datetime.now() print(humanize.naturaltime(now - timedelta(days=1))) # "il y a 1 jour" print(humanize.intcomma(1234567)) # "1 234 567" (space separator)

Not every locale is fully translated, and the separator for intcomma varies by locale (comma, period, or space). If your application targets multiple regions, test the output for each locale you support. Note that activate changes the global locale, so if you need different locales in a multi-threaded web server, manage that at a higher level rather than switching the global locale per request.

Performance and Formatting Considerations

These functions are lightweight and perform well for typical UI rendering. naturaltime and naturaldate do a small amount of date arithmetic and string formatting, while intcomma does a regex-based insertion. None of them involve I/O or heavy computation, so they are safe to call in request handlers or loops that process thousands of items.

naturaltime and naturaldate depend on the current date and time when called, so the output can change between calls. If you want all rows in a report or loop to use the same reference point, compute a datetime once and pass it to naturaltime via the optional when argument. The humanized strings are for display only: if you need to store or compare these values, keep the original timestamp or number separately.

Edge Cases and Behavior with Different Input Types

All three functions accept multiple input types, but the behavior can differ in subtle ways.

naturaltime accepts datetime, date, timedelta, and numeric timestamps (Unix time). For a numeric timestamp, it interprets the value as seconds since the epoch. Passing a date object works, but it treats the date as midnight, so the relative time will be based on that instant.

naturaldate only cares about the calendar date. If you pass a datetime, it ignores the time part. If you pass a timedelta, it treats it as a relative offset from today, so naturaldate(timedelta(days=2)) returns the date two days from now.

intcomma handles negative numbers and floats. It also formats numeric strings, but the result for malformed input is less predictable. If you are not sure what type you are passing, convert to a numeric type before calling the function.

These edge cases are not bugs; they are the result of the library's design to keep the API simple. When you know the exact type you are passing, the behavior is predictable. When you are unsure, convert to a known type before calling the function.

For most applications, naturaltime, naturaldate, and intcomma give you exactly the formatting you need without writing custom date and number formatting code. They are small, focused utilities that make output friendlier while keeping your codebase clean.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.