Install & Compatibility
Where this runs
tested against v1.0.16 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.004s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.002s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
format
✓ from timeago import format
✗ import timeago
This quickstart demonstrates the core `timeago.format()` function with `datetime.datetime` objects and `datetime.timedelta`. It also shows how to specify a different locale.
import timeago
import datetime
# Get current time for comparison
now = datetime.datetime.now()
# Example 1: Past datetime
past_date = datetime.datetime.now() - datetime.timedelta(days=2, hours=3, minutes=30)
print(f"Past date: {timeago.format(past_date, now)}")
# Example 2: Future datetime (relative to now)
future_date = datetime.datetime.now() + datetime.timedelta(hours=5)
print(f"Future date: {timeago.format(future_date, now)}")
# Example 3: Using a timedelta directly
time_delta_example = datetime.timedelta(seconds=60 * 3.4)
print(f"Timedelta: {timeago.format(time_delta_example)}")
# Example 4: With a specific locale (e.g., Chinese Simplified)
# Ensure your system supports UTF-8 for printing non-ASCII characters
print(f"Locale example (zh_CN): {timeago.format(past_date, now, 'zh_CN')}")
Debug
Known issues
gotchaThe library is designed for human-readable approximations (e.g., '3 minutes ago') rather than precise duration reporting. If exact time differences like '1 month 19 days ago' are required, consider libraries such as `dateutil.relativedelta` instead.fixUse libraries like `dateutil.relativedelta` for precise duration calculations.
affects: All versions
gotchaUsers must handle timezone awareness consistently when providing `datetime` objects to `timeago.format()`. Mixing timezone-naive and timezone-aware datetimes can lead to unexpected results. Note that `datetime.datetime.utcnow()` is deprecated in Python 3.12+; the recommended approach for UTC is `datetime.datetime.now(datetime.UTC)`.fixEnsure all `datetime` objects passed to `timeago.format()` are consistently timezone-aware or consistently timezone-naive. For UTC, use `datetime.datetime.now(datetime.UTC)` in Python 3.12+.
affects: All versions, particularly relevant for Python 3.12+
gotchaWhen bundling applications with PyInstaller, `timeago`'s locale files might not be automatically included, leading to `ModuleNotFoundError` for locales.fixAdd hidden imports for `timeago.locales` to your PyInstaller spec file to ensure locale files are bundled, e.g., `hiddenimports=['timeago.locales']` or `timeago.locales.en`, `timeago.locales.zh_CN` for specific locales.
affects: All versions when used with PyInstaller
Upgrade
Version history
1.0.16latest on PyPI · released Aug 18, 2022
Audit
Dependencies
No dependency data recorded yet.