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.

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:
pip install humanizeOnce installed, import the functions you need directly:
from humanize import naturaltime, naturaldate, intcommaAll 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.
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:
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.
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 todayFor 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.
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:
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.
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:
Last seen: 5 hours ago
File size: 8,451,234 bytes
Report date: todayBecause 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.
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.