Dealing with time and date formatting is a common task in many software applications. When presenting timestamps to users, it's often preferable to show them in a more human-readable format, such as "2 hours ago" or "3 days ago," rather than an exact timestamp. The 'timeago' Python package provides a straightforward way to accomplish this. In this article, we'll explore how to use this handy library to simplify date and time representation in Python.

What is 'timeago'?

timeago is a Python library that facilitates the conversion of datetime objects or timestamps into human-readable relative times. Instead of displaying "2023-10-15 14:40:00," with 'timeago', you can show "15 minutes ago," making it more intuitive for end-users.


Before we dive into using 'timeago', you'll need to install it. Use pip for a quick installation:

pip install timeago

Basic Usage

Here's how you can convert a datetime object to a human-readable format using 'timeago':

import timeago
import datetime

# Create a datetime object for a time in the past
past_date = - datetime.timedelta(hours=2, minutes=15)

# Convert to a human-readable format
formatted_time = timeago.format(past_date,
2 hours ago

Note that the timeago.format() function requires two arguments: the past datetime and the current datetime. The difference between them is calculated and then presented in a user-friendly format.

Handling Different Locales

One of the advantages of 'timeago' is its support for various languages. This feature is particularly useful if you're developing a multi-language application. Here's how you can display the relative time in Spanish:

# Ensure you set the right locale
formatted_time_es = timeago.format(past_date,, 'es')
hace 2 horas

You can get list of all locales from timeago repository.

Advanced Features

'timeago' also comes with several additional features and utilities to customize its behavior.

1. Using with Timestamps

If you have a timestamp instead of a datetime object, you can still use 'timeago' without any issues:

import time

# Current time as a timestamp
now_timestamp = time.time()

# A timestamp for 45 seconds ago
past_timestamp = now_timestamp - 45

# Format it
formatted_time_seconds = timeago.format(datetime.datetime.fromtimestamp(past_timestamp), datetime.datetime.fromtimestamp(now_timestamp))
45 seconds ago

2. Limiting Time Frames

If you want to limit the maximum unit used, you can achieve this by setting the max_seconds parameter:

formatted_time_limit = timeago.format(past_date,, max_seconds=3600)
print(formatted_time_limit)  # Outputs: "135 minutes ago" instead of "2 hours ago"

The timeago library in Python offers a convenient solution for displaying time in a format that's more intuitive and user-friendly. Whether you're working on a web application, a CLI tool, or any other software, presenting time as "2 hours ago" or "3 days ago" enhances user experience and comprehension. With timeago, achieving this is just a few lines of code away.

For more details and documentation, visit timeago official repository.