---
id: timeago
version: "1.0.16"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# timeago — A very simple python library, used to format datetime with `*** time ago` statement. eg: "3 hours ago".

License: permissive · Maintenance: abandoned · Downloads: 1.0M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: abandoned
- Downloads: 1.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

relative time formatting, time ago display, human readable timestamps, datetime to text conversion, locale aware time formatting, fuzzy time display, past and future time ago, datetime-formatting, i18n, abandoned

[View on SkillFed](https://skillfed.io/packages/timeago) · [View on PyPI](https://pypi.org/project/timeago/)