time library

time documentation

The time module reads the system clock, pauses a program for a set number of seconds, and measures how long a piece of code takes to run.

	`time`	`datetime`
Focus	The system clock, code timing, and pausing execution.	Calendar dates, date arithmetic, and human-readable date/time values.
Time format	A Unix timestamp — a plain float counting seconds since the epoch.	High-level objects — `date`, `time`, `datetime`, `timedelta`.
Timezone support	Limited — relies on the system's local time.	Full — handles timezone-aware dates and conversions.
Common uses	Benchmarking how long code takes to run Pausing a program with `sleep()`	Logging when something happened Calculating an age or a deadline Date arithmetic

Setup

time ships with Python's standard library — nothing to install. The whole module is used through the time. prefix, so a plain import is all you need.

import time

Function	Returns	Example
`time()`	Seconds since the epoch, as a float	`1785024000.0`
`sleep(seconds)`	Pauses the program, returns `None`	`sleep(2)`
`perf_counter()`	A high-resolution timer, for measuring durations	`perf_counter()`
`localtime()`	The current time as a `struct_time`	`localtime()`
`strftime(format, t)`	A `struct_time` formatted as a string	`strftime("%H:%M", localtime())`

Reading the clock

time() returns the number of seconds since the epoch¹ — a single float that always increases, useful for a timestamp or for logging when an observation happened.

import time

print(time.time())

Pausing execution

sleep() pauses the program for the given number of seconds before continuing to the next line. Useful for spacing out repeated print() calls, or waiting between requests to an external service.

import time

print("checking on the burmese python...")
time.sleep(1)
print("still there.")

Run a pausing example

All the examples above, combined into one script:

import time

print(time.time())

import time

print("checking on the burmese python...")
time.sleep(1)
print("still there.")

Measuring elapsed time

perf_counter() reads a high-resolution timer meant for measuring durations, not for reading the wall-clock date — call it before and after a block of code, then subtract the two readings to get the elapsed time in seconds.

import time

start = time.perf_counter()
total = sum(range(1_000_000))
elapsed = time.perf_counter() - start

print(elapsed)

Why not time() for this?

time() tracks the system clock, which can jump backward or forward (a clock sync, daylight saving). perf_counter() is unaffected by that — it only ever counts forward, which makes it the right tool for timing how long code takes to run.

Run a measuring elapsed time example

All the examples above, combined into one script:

import time

start = time.perf_counter()
total = sum(range(1_000_000))
elapsed = time.perf_counter() - start

print(elapsed)

Formatting the current time

localtime() returns a struct_time — the current date and time broken into named fields (tm_year, tm_hour, tm_min, and so on). strftime() turns one into a custom-formatted string, using the same format codes as datetime's strftime: %H the zero-padded hour, %M the zero-padded minute.

import time

now = time.localtime()
time.strftime("%H:%M", now)    # "14:30"

Reaching for datetime instead

time works with a struct_time, a plain tuple of fields, which has no date arithmetic of its own — no adding a week, no subtracting two times. For anything beyond formatting the current moment, the datetime module's date and datetime objects are the better fit.

Run a formatting example

All the examples above, combined into one script:

import time

now = time.localtime()
print(time.strftime("%H:%M", now))

The epoch is a fixed reference point, midnight, January 1, 1970 (UTC). "Seconds since the epoch" is just a plain number, not tied to any calendar, which is why it's easy to compare or subtract. ↩