---
id: ago
version: "0.1.1"
license: Public Domain
license_treatment: permissive
maintenance: active
---

# ago — ago: Human readable timedeltas

License: permissive · Maintenance: active · Downloads: 104.9K/mo

## What it is and what it does

ago is a lightweight utility that transforms time intervals into natural-language phrases. It accepts a datetime object (to compute elapsed or future time relative to now), a timedelta object, or a raw timestamp, and produces strings like 'created 1 year, 127 days ago' or 'due in 2 days, 3 hours'. The core function is `human()`, which takes a time input and optional parameters for precision (how many time units to show), tense templates (past/future format strings), and abbreviation (to produce '5d, 3h' instead of '5 days, 3 hours'). It also exposes lower-level functions like `delta2dict()` and `extract_components()` for cases where you need to work with the time breakdown directly rather than a formatted string.

The package has no external dependencies and installs as a pure Python wheel, making it suitable for embedding in applications that need to display relative timestamps in logs, UI, or API responses. It's particularly useful when you want consistent, customizable phrasing for time intervals without writing your own formatting logic.

Use it for:

- Display activity timestamps in web interfaces or logs (e.g., 'User commented 2 days, 5 hours ago').
- Format scheduled task or job descriptions (e.g., 'Job will run in 3 days, 2 hours from now').
- Generate human-friendly uptime or elapsed-time summaries in monitoring dashboards.
- Customize time-ago phrases for different contexts or languages via past_tense and future_tense templates.
- Build time-unit breakdowns programmatically using delta2dict or extract_components for further processing.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts datetime, timedelta, and timestamp objects into human-readable time phrases like '1 year, 127 days ago' or 'in 2 days, 3 hours', with customizable precision, tense, and abbreviation.

Yes. The package is lightweight, dependency-free, actively maintained (recent release), permissively licensed, and solves a common formatting need. Install it if you need to display relative timestamps in human-readable form; skip it only if you're already using a heavier datetime library that includes this feature.

## Install

pip install ago
uv add ago
poetry add ago

## Installing ago

Before you install: Low friction: pure Python wheel with no runtime dependencies and a recent release (43 days old). Maintenance status is active.

License in practice: Public Domain license means unrestricted use, modification, and distribution with no attribution or liability concerns.

Quickstart:

pip install ago

from ago import human
from datetime import datetime, timedelta

db_date = datetime(year=2010, month=5, day=4, hour=6, minute=54, second=33)
print('Created ' + human(db_date))  # "Created X years, Y months ago"

delta = timedelta(days=5, hours=3, minutes=45)
print('Due in ' + human(delta))  # "Due in 5 days, 3 hours"

Verify before relying:

- Whether Python version support is truly unspecified or if there are practical constraints not documented in the fact sheet.
- Whether the package is actively maintained beyond the recent release date, given that repository metadata (stars, last commit) is unavailable.

## Package facts

- License: Public Domain (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 104.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

human readable timedelta, format time ago, datetime to readable string, relative time formatting, time delta humanizer, pretty print timedelta, time ago formatter, datetime-formatting, relative-time

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