{"id":5079,"library":"timeago","title":"Timeago (Python)","description":"A very simple Python library, used to format datetime with a \"*** time ago\" statement, e.g., \"3 hours ago\". The current version is 1.0.16. The project has a slower release cadence, with the last release in August 2022, but it is actively maintained.","status":"active","version":"1.0.16","language":"en","source_language":"en","source_url":"https://github.com/hustcc/timeago","tags":["datetime","time","formatting","relative time","localization"],"install":[{"cmd":"pip install timeago","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The primary functionality is exposed via the `format` function directly under the `timeago` module.","symbol":"format","correct":"import timeago\n\ntimeago.format(...)"}],"quickstart":{"code":"import timeago\nimport datetime\n\n# Get current time for comparison\nnow = datetime.datetime.now()\n\n# Example 1: Past datetime\npast_date = datetime.datetime.now() - datetime.timedelta(days=2, hours=3, minutes=30)\nprint(f\"Past date: {timeago.format(past_date, now)}\")\n\n# Example 2: Future datetime (relative to now)\nfuture_date = datetime.datetime.now() + datetime.timedelta(hours=5)\nprint(f\"Future date: {timeago.format(future_date, now)}\")\n\n# Example 3: Using a timedelta directly\ntime_delta_example = datetime.timedelta(seconds=60 * 3.4)\nprint(f\"Timedelta: {timeago.format(time_delta_example)}\")\n\n# Example 4: With a specific locale (e.g., Chinese Simplified)\n# Ensure your system supports UTF-8 for printing non-ASCII characters\nprint(f\"Locale example (zh_CN): {timeago.format(past_date, now, 'zh_CN')}\")","lang":"python","description":"This quickstart demonstrates the core `timeago.format()` function with `datetime.datetime` objects and `datetime.timedelta`. It also shows how to specify a different locale."},"warnings":[{"fix":"Use libraries like `dateutil.relativedelta` for precise duration calculations.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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+.","message":"Users 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)`.","severity":"gotcha","affected_versions":"All versions, particularly relevant for Python 3.12+"},{"fix":"Add 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.","message":"When bundling applications with PyInstaller, `timeago`'s locale files might not be automatically included, leading to `ModuleNotFoundError` for locales.","severity":"gotcha","affected_versions":"All versions when used with PyInstaller"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}