timeago

What it is and what it does

timeago is a minimal library that converts datetime objects, timedeltas, or datetime strings into relative time expressions (e.g., '3 minutes ago', 'in 2 hours', 'just now'). It accepts a date to format, a reference time, and an optional locale code, then returns a human-readable string. The library supports many locales including ar, bg, ca, da, de, el, en, en_short, es, eu, fa_IR, fi, fr, gl, guj_IN, he, hu, in_BG, in_HI, in_ID, is, it, ja, ko, lt, ml, my, nb_NO, nl, nn_NO, pl, pt_PT, pt_BR, ro, ru, sk, sv_SE, ta, th, tr, uk, vi, zh_CN, and zh_TW.

The package has no external runtime dependencies and installs as a pure Python wheel. However, it is no longer maintained—the last commit was 2022-09-14. While it may continue to work for straightforward use cases, it will not receive updates, bug fixes, or compatibility improvements for newer Python versions.

Use it for:

• Display activity timestamps in web applications (e.g., 'posted 2 hours ago')
• Format notification or log timestamps for end-user display in multiple languages
• Convert database timestamps to relative time in API responses
• Show relative times in chat or social media interfaces
• Localize time expressions for international audiences without manual translation

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Formats datetime objects and timedeltas into human-readable relative time strings like '3 minutes ago' or 'in 2 hours', with support for multiple locales.

Yes, if you need simple relative time formatting and can tolerate an unmaintained package. The library is stable, has no dependencies, and works for basic use cases. However, do not use it if you require active maintenance, compatibility with the latest Python versions, or ongoing locale updates. For new projects, consider an actively maintained alternative.

Install

timeago on PyPI

pip install timeago

uv add timeago

poetry add timeago

Installing timeago

Before you install

Low install friction with no runtime dependencies. However, the package is abandoned—last commit was 2022-09-14 and no releases since the latest release on 2022-08-18. It may work for simple use cases but will not receive maintenance or security updates.

License in practice

MIT license is permissive and places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

import timeago
import datetime

now = datetime.datetime.now()
date = datetime.datetime.now() - datetime.timedelta(minutes=3)
print(timeago.format(date, now))  # prints: 3 minutes ago

Verify before relying

• Whether the package works correctly with modern Python versions despite classifiers only listing up to 3.5
• Current state of all listed locale implementations and whether they are fully functional
• Whether any breaking changes in Python's datetime module affect this package since 2022-09-14

Package facts

Evidence: timeago-1.0.16-py3-none-any.whl

Keywords: timeago, seconds ago, minutes ago, hours ago, just now

Tags

More Utilities packages