time — time access and conversions

time.gmtime and strftime with a fixed timestamp, and a text-only note on monotonic clocks. This is not the datetime module.

模块页正文目前为英文。

The time module converts Unix timestamps and formats struct_time values. Import it as import time. The datetime page already covers calendar dates, timedelta, and timezone-aware datetime objects. This page stays with timestamps, gmtime, and strftime.

Examples use a fixed timestamp so the output does not depend on the current clock. time.time() and date.today() are a poor fit for expected-output examples. time.localtime and locale-dependent format codes such as %A or %c can vary by timezone or locale; the examples use gmtime and numeric format codes only.

time.monotonic() is a monotonic clock for measuring intervals. It is not a wall-clock timestamp, it is not comparable across processes, and it is not convertible to UTC by itself. This page explains it in the text only. The examples do not call it, do not print an elapsed value, and do not call time.sleep.

Examples were run against Python 3.13.12. Links point to the Python 3.13 documentation.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

gmtime and strftime on a fixed timestamp

time.gmtime(secs) converts a timestamp into a UTC struct_time. The year, month, day, and time fields below are for 1_000_000_000 seconds after the Unix epoch, which is 2001-09-09 01:46:40 UTC, and for timestamp 0, which is 1970-01-01 00:00:00 UTC. tm_wday is 6 for Sunday, tm_yday is the day of the year, and tm_isdst is 0 in UTC.

time.strftime formats a struct_time. The format used here is %Y-%m-%dT%H:%M:%SZ, which does not depend on the process locale.

time.gmtime and time.strftime

time.gmtime([secs])
time.strftime(format[, t])

Convert two fixed UTC timestamps to struct_time and format them as ISO-like text.

ParameterDescription
secsSeconds since the Unix epoch. The example passes 1_000_000_000 and 0. If omitted, gmtime would use the current time, which this page does not print.
format, tA strftime format string and a struct_time. When t is omitted, strftime would use the local time; this example always passes the gmtime result.

Returns: gmtime returns a struct_time. strftime returns a string.

Raises

  • ValueError / OverflowError — Raised for a timestamp outside the range the platform can represent, or for an invalid format string.
  • These official signatures are written as in the Python 3.13 time documentation, which uses optional arguments in brackets.
python
import time

ts = 1_000_000_000
utc = time.gmtime(ts)
print(utc.tm_year, utc.tm_mon, utc.tm_mday, utc.tm_hour, utc.tm_min, utc.tm_sec, utc.tm_wday, utc.tm_yday, utc.tm_isdst)
print(time.strftime("%Y-%m-%dT%H:%M:%SZ", utc))
print(time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(0)))

Expected output

2001 9 9 1 46 40 6 252 0
2001-09-09T01:46:40Z
1970-01-01T00:00:00Z

Related: datetime (dates and timezones), zoneinfo

Official documentation →

monotonic is for intervals, not timestamps

time.monotonic() returns a float that only moves forward, including during a system clock change. Official documentation says it is used for measuring durations, and that the reference point is undefined, so the raw value is not a Unix timestamp and cannot be converted to UTC on its own. Values from different processes, or from before and after a machine reboot, are not comparable.

Because any printed difference depends on how long the process ran, this page does not call time.monotonic() or time.sleep() in an example, and it does not claim a particular elapsed number. Use gmtime when you need a stable wall-clock conversion, and use datetime when you need a calendar value or a timezone.

time.monotonic (described, not timed)

time.monotonic()

A monotonic clock for intervals. This entry records the documented meaning; it does not print a reading.

Returns: A float in seconds. The starting point is unspecified.

  • This example only prints a fixed reminder so the page still has a deterministic program. It does not measure elapsed time.
python
print("monotonic measures intervals; the raw value is not a UTC timestamp")

Expected output

monotonic measures intervals; the raw value is not a UTC timestamp

Related: datetime

Official documentation →