Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Math, Data and Text

The time module

Reference for Python's time module: epoch timestamps, sleep, monotonic and perf_counter clocks, struct_time, strftime, gmtime and mktime with examples.

The time module gives low-level access to clocks and to the operating system's idea of time. It is the place for timestamps (seconds since the epoch, 1970-01-01 00:00:00 UTC on most systems), for pausing a program with sleep(), and for measuring how long code takes to run.

For calendar-style work such as adding days, parsing dates or handling time zones, use datetime instead. The two modules complement each other: time is about instants and clocks, datetime about human dates.

Python
import time

start = time.perf_counter()
time.sleep(0.01)
elapsed = time.perf_counter() - start

Try it

Python Epoch, struct_time and formatting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Sleeping and measuring

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Main functions

Function Returns
time.time() Seconds since the epoch as a float. Affected by system clock changes.
time.time_ns() The same as an integer number of nanoseconds (no float rounding).
time.sleep(seconds) Pauses the calling thread. Accepts fractions. Returns None.
time.monotonic() A clock that only moves forward, suited to timeouts. Reference point is undefined.
time.perf_counter() The highest-resolution clock for measuring short intervals.
time.process_time() CPU time used by the current process (excludes sleeping).
time.gmtime(secs=None) A struct_time in UTC.
time.localtime(secs=None) A struct_time in the local zone.
time.mktime(t) Converts a local struct_time to seconds (inverse of localtime).
time.strftime(format, t) Formats a struct_time as text.
time.strptime(text, format) Parses text into a struct_time.

struct_time is a named tuple with tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday (Monday is 0), tm_yday (1-366) and tm_isdst.

Usage notes

  • Measure with perf_counter(), not time(). time() can jump when the system clock is corrected, which gives negative or wrong durations. For benchmarking small snippets, timeit does the repetition for you.
  • sleep() is at least, not exactly. The actual pause can be longer because of scheduling. It blocks only the current thread, and a negative argument raises ValueError.
  • sleep() blocks an event loop. In asyncio code use await asyncio.sleep().
  • time.time() is in UTC seconds, but localtime() and mktime() depend on the machine's time zone, so results differ between computers. Prefer aware datetime objects when zones matter.
  • Float precision. A float holds about microsecond precision for current timestamps; time_ns() avoids that loss.
  • Epoch differences. The epoch is platform defined; check time.gmtime(0) if it matters.
  • Python 3.13 and later run time.sleep() on a high-resolution timer on Windows, which makes very short sleeps more accurate.