Skip to main content

Timestamp library and utility

tslib is a timestamp processing toolkit and library, written in Python. It is very helpful when dealing with the millisecond-precision timestamps that we encounter all the time in computer systems, and to work with human-readable time deltas away from “now”.

Installation

You can install tslib directly from PyPI with the following command:

$ pip install tslib

If you’re installing from a clone of this repository, use:

$ git clone https://github.com/mpetazzoni/tslib
$ cd tslib/
$ pip install -e .

tslib requires Python 3.11 or newer. Named timezones use Python’s zoneinfo module and the system IANA timezone database, with the automatically installed tzdata package as a fallback. Neither pytz nor six is required.

You’re now ready to use ts, which should be directly available in your $PATH.

Usage

$ ts -h
usage: ts [-h] [-t TZ] [-n] [-i] [-a {minute,hour,day}]

Human readable timestamps

options:
  -h, --help            show this help message and exit
  -t, --timezone TZ     Use IANA timezone TZ (default: OS local timezone)
  -n, --timestamp-only  Only output the resulting millisecond timestamp(s)
  -i, --inline          Apply timestamp replacements inline of the incoming
                        text
  -a, --align {minute,hour,day}
                        Align the timestamp

ts transforms milliseconds timestamps and human-readable deltas into fully qualified date and time printouts, containing:

  • the UTC timestamp (since Epoch)

  • the UTC time represented by the timestamp

  • the local time represented by the timestamp

  • the human-readable delta of this timestamp against current time

The output is tab-delimited and can easily be re-segmented by piping into column -t -s "\t".

Arguments can be passed as command-line arguments, or piped into ts via STDIN. If no input comes from either of these sources, ts will simply output the current time:

$ ts -t America/Los_Angeles
1423599084206 2015-02-10 20:11:24.206 UTC+0000  2015-02-10 12:11:24.206 PST-0800  0

Inline mode

ts can operate in inline-replacement mode, for timestamps only. In this mode, you can pipe in any text and ts will output it back to you with all timestamps replaced with a human-readable date and time and human-readable delta representation.

Given the inherent difficulty of accurately matching timestamps, the matching is limited to 13-digits millisecond precision timestamps (that may be immediately followed by a L). Numbers smaller, or larger than 13 digits are not matched, and are left alone; meaning no 13-digit section of them is matched and replaced.

$ echo B_b-3PAAYAA B_cJXlvAYAA B_cJXl6AcAA \
    | xargs sfc mb g -p TSVH -f sf_checkpointTimestampMs -f sf_updatedOnMs \
    | ts -i -t America/Los_Angeles \
    | column -t -s "    "
sf_id        sf_checkpointTimestampMs                              sf_updatedOnMs
B_b-3PAAYAA  2015-03-06 13:38:58.851 PST-0800 (-2w5h18m6s210)      2015-03-06 13:38:58.852 PST-0800 (-2w5h18m6s209)
B_cJXlvAYAA  2015-03-08 09:04:36.218 PDT-0700 (-1w5d10h52m28s843)  2015-03-08 09:04:36.218 PDT-0700 (-1w5d10h52m28s844)
B_cJXl6AcAA  2015-03-08 09:04:34.252 PDT-0700 (-1w5d10h52m30s810)  2015-03-08 09:04:34.342 PDT-0700 (-1w5d10h52m30s720)

More examples

Piping:

$ cat << EOF | ts -t America/Los_Angeles
pipe heredoc> 1404424797009L
pipe heredoc> 1415917836779L
pipe heredoc> EOF
1404424797009 2014-07-03 21:59:57.009 UTC+0000  2014-07-03 14:59:57.009 PDT-0700  -31w5d1h14m26s38
1415917836779 2014-11-13 22:30:36.779 UTC+0000  2014-11-13 14:30:36.779 PST-0800  -12w5d43m46s268

Using the column output (assuming the same input in a /tmp/ts.txt file):

$ cat /tmp/ts.txt | ts | cut -f4
-31w5d1h16m17s703
-12w5d45m37s933

Sorting on a column (here, by descending timestamps in first column):

$ cat /tmp/ts.txt | ts -t America/Los_Angeles | sort -k1 -t $'\t' -r
1415917836779 2014-11-13 22:30:36.779 UTC+0000  2014-11-13 14:30:36.779 PST-0800  -12w5d46m6s924
1404424797009 2014-07-03 21:59:57.009 UTC+0000  2014-07-03 14:59:57.009 PDT-0700  -31w5d1h16m46s694

Deltas

Human-readable deltas can be expressed in weeks (w), days (d), hours (h), minutes (m), and seconds (s). The remainder, without a unit, is assumed to be milliseconds. Any “segment” can be omitted, the only requirement is that the segments that are specified are written in descending order of span (days before hours, hours before minutes, etc.).

Here’s an example: -12w4d6m57s257. Note that hours are missing, which simply means 12 weeks, 4 days, 6 minutes, 57 seconds and 257 milliseconds.

As you might have guessed, deltas can be both negative and positive. For positive deltas, the leading + may be omitted if units are used, otherwise the number is assumed to be an absolute timestamp:

$ ts -t America/Los_Angeles -1
1423599850752 2015-02-10 20:24:10.752 UTC+0000  2015-02-10 12:24:10.752 PST-0800  -1
$ ts -t America/Los_Angeles 0 1
            0 1970-01-01 00:00:00.000 UTC+0000  1969-12-31 16:00:00.000 PST-0800  -2353w5d20h24m14s145
            1 1970-01-01 00:00:00.001 UTC+0000  1969-12-31 16:00:00.001 PST-0800  -2353w5d20h24m14s144
$ ts -t America/Los_Angeles +1
1423599855941 2015-02-10 20:24:15.941 UTC+0000  2015-02-10 12:24:15.941 PST-0800  1

Using a different local timezone

The third column shows the timestamp’s representation in local time. By default it uses the operating system’s configured local timezone, including the daylight-saving offset appropriate to the timestamp being converted. It does not depend on the legacy US/Pacific timezone alias. On POSIX systems, the TZ environment variable can override the local timezone.

Use -t to select an explicit IANA timezone name, such as UTC, America/Los_Angeles, or Europe/Paris. Invalid names produce a command-line usage error. The Pacific-time examples above explicitly select America/Los_Angeles so their output does not depend on the host timezone:

$ ts -t Europe/Paris
1423600015955 2015-02-10 20:26:55.955 UTC+0000  2015-02-10 21:26:55.955 CET+0100  0

Absolute, human-readable offsets from Epoch

By prefixing a human-readable delta with an equal sign (=), you obtain an absolute offset from the Epoch. The side-effect of this is that it allows for converting a human-readable delta into its corresponding millisecond duration.

$ ts -n '=1h'
      3600000
$ ts -t America/Los_Angeles '=1d'
     86400000 1970-01-02 00:00:00.000 UTC+0000  1970-01-01 16:00:00.000 PST-0800  -2365w6d21h56m20s98

Alignment

-a minute, -a hour, and -a day round forward to the next UTC boundary, even if the timestamp is already aligned. The chosen display timezone does not change the alignment:

$ ts -n -a hour 1
      3600000

Library compatibility

UTC datetime helpers now return standard-library datetime objects with datetime.timezone.utc rather than pytz.utc. date_from_utc still requires a naive datetime and rejects an already timezone-aware value. Replace pytz-specific operations such as localize and normalize with standard-library datetime operations when upgrading.

render_date(date) keeps its UTC display default for library callers. Pass None to use the OS-local timezone, or a zoneinfo.ZoneInfo object to select a named timezone:

from zoneinfo import ZoneInfo
from tslib import date_from_utc_ts, render_date

print(render_date(date_from_utc_ts(1404424797009), ZoneInfo("Europe/Paris")))

Development

Install the development dependencies in a virtual environment, then run:

$ python -m pip install -e '.[dev]'
$ python -m pytest
$ python -m ruff check .
$ python -m build
$ python -m twine check dist/*

CI runs these checks on Python 3.11 through 3.14 on Linux, macOS, and Windows.

Metadata

Release files for tslib 2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tslib 2.0
File Size Uploaded Provenance Actions
tslib-2.0.tar.gz 16.5 kB With provenance Details for tslib-2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tslib 2.0
File Interpreter ABI Platform Actions
tslib-2.0-py3-none-any.whl Python 3 none any Details for tslib-2.0-py3-none-any.whl

Total release size: 28.4 kB

Release files / tslib-2.0.tar.gz

Download URL tslib-2.0.tar.gz
Size 16.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b6c269ccc8a78d1292b38585044144753350e8af6685a0ad21ec37cd248ad8eb
BLAKE2b-256 checksum
How to use checksums
2f69da2e7bd5c8e8597fcf146792d43cfe4f2cae9fccc9f9784a9f80a2d362f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / tslib-2.0-py3-none-any.whl

Download URL tslib-2.0-py3-none-any.whl
Size 11.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6c207b702d0b42b5204bc60f149eb3ff554bd04ea777d4c8394e064ed4aca07e
BLAKE2b-256 checksum
How to use checksums
89e8ae6dcbacba692169dd901fd8173491aab2525615724328217b488283ea34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for tslib 2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tslib-2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page