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.
import time start = time.perf_counter() time.sleep(0.01) elapsed = time.perf_counter() - start
Try it
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.
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(), nottime().time()can jump when the system clock is corrected, which gives negative or wrong durations. For benchmarking small snippets,timeitdoes 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 raisesValueError.sleep()blocks an event loop. Inasynciocode useawait asyncio.sleep().time.time()is in UTC seconds, butlocaltime()andmktime()depend on the machine's time zone, so results differ between computers. Prefer awaredatetimeobjects 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.
Related
datetime,calendar,timeit,ValueError- Lessons: Dates and times, Performance