Monotonic Time Backport

1.6 · maintenance · verified Sun Apr 05

This library provides a backport of Python's `time.monotonic()` function for older Python environments (Python 2 and Python < 3.3). It offers a monotonic clock, guaranteed not to go backward, which is crucial for reliably measuring elapsed time, as it remains unaffected by system clock adjustments such as daylight saving changes. The current version is 1.6. The library is considered stable and complete, with no further updates planned, as `time.monotonic()` is integrated into the standard library for Python 3.3 and newer.

Warnings

deprecated For Python 3.3 and newer, `time.monotonic()` is part of the standard library. Using this `monotonic` package on these versions is redundant and unnecessary, though it will gracefully alias the built-in function. Prefer `time.monotonic()` directly for modern Python versions to avoid unnecessary dependencies.
Fix: Remove `monotonic` from your dependencies and use `from time import monotonic` directly.
gotcha The value returned by `monotonic.monotonic()` (or `time.monotonic()`) has an undefined reference point. Only the *difference* between two calls to the function is meaningful for measuring elapsed time; the absolute value itself should not be relied upon. Comparing values from different processes might also be unreliable on some OS.
Fix: Always calculate durations by subtracting an earlier `monotonic()` call from a later one (e.g., `end_time - start_time`).
gotcha The precision of the monotonic clock can vary by operating system. Specifically, on some Windows implementations, `monotonic.monotonic()` (and `time.monotonic()`) might offer less decimal precision compared to `time.time()`, typically around three decimal places.
Fix: Be aware of potential precision limitations on Windows. If nanosecond precision is required on modern Python, `time.monotonic_ns()` might be an alternative (available in Python 3.7+), but this library does not provide that.
breaking If the `monotonic` library cannot find a suitable underlying system implementation for a monotonic clock on the current platform, attempting to import the module or its functions will raise a `RuntimeError`.
Fix: Ensure the target platform has a compatible system clock. Common platforms like Linux, Windows, macOS, BSD, and AIX are supported.

Install

pip install monotonic Install stable version

Imports

monotonic
```
import monotonic
start = monotonic.monotonic()
```
The `monotonic` package provides the `monotonic()` function. For Python versions < 3.3, `time.monotonic()` does not exist in the standard library. For cross-version compatibility, you might use a conditional import: `try: from time import monotonic as get_monotonic_time_fn except ImportError: from monotonic import monotonic as get_monotonic_time_fn`

Quickstart

This quickstart demonstrates how to use the `monotonic` function to measure elapsed time, ensuring that clock adjustments do not affect the duration measurement. It includes a robust import pattern for compatibility across Python 2 and Python 3.3+.

import time

# For compatibility across Python versions, prefer this pattern:
try:
    from time import monotonic as get_monotonic_time_fn
except ImportError:
    # Fallback for Python 2 and Python < 3.3 using the 'monotonic' package
    from monotonic import monotonic as get_monotonic_time_fn

print('Starting a monotonic timer...')
start_time = get_monotonic_time_fn()

# Simulate some work
time.sleep(2.5)

end_time = get_monotonic_time_fn()
elapsed_time = end_time - start_time

print(f'Elapsed time: {elapsed_time:.3f} seconds')

view raw JSON →