time
The time module reads the clocks, pauses the program, and turns times into text and back: RFC 3339 timestamps, strftime-style layouts, calendar fields in UTC or the local time zone, and durations like "1h30m". A time is a float of seconds since the Unix epoch, the value time.now() returns, so times compare, subtract and store as plain numbers.
import time
fn main():
start = time.now_ms()
time.sleep(20)
elapsed = time.now_ms() - start
print(elapsed >= 20, elapsed < 1000)true truenow
fn now() floatThe current time in seconds since the Unix epoch (1970-01-01 00:00:00 UTC), with a fraction for the sub-second part (to about a microsecond at today's dates).
now_ms
fn now_ms() intThe current time in milliseconds since the Unix epoch, as a whole number. It is the same clock as now, so time.now_ms() / 1000 equals int(time.now()) (give or take the moment between the two calls). Use now_ms for timestamps you store or compare, since int arithmetic is exact.
import time
fn main():
s = time.now()
ms = time.now_ms()
print(s > 1_700_000_000.0, ms > 1_700_000_000_000)
print(ms / 1000 - int(s) <= 1)
day = ms / 86_400_000 # whole days since 1970-01-01
print(day > 19_000)true true
true
trueBoth read the wall clock (CLOCK_REALTIME). If the system clock is changed (by NTP or by hand), the next reading jumps with it, so a duration measured across that change can be wrong or even negative. For timing code that is almost never an issue, but don't rely on two readings being in order.
sleep
fn sleep(ms: int)Pauses the current thread for at least ms milliseconds (the operating system may wake it a little later). sleep(0) and negative values return at once. Inside a parallel block only the task that calls it waits; the others keep running.
import time
fn main():
for i in 0..3:
print("tick", i)
time.sleep(10)
time.sleep(0)
time.sleep(-5)
print("done")tick 0
tick 1
tick 2
doneMonotonic clock
fn mono_ns() int
fn mono_ms() intA clock that only moves forward, for measuring how long something took: unlike now, it doesn't jump when the system clock is set. Its zero point is arbitrary (usually boot).
Formatting and parsing
fn rfc3339(t: float) str "2026-09-28T06:45:12Z", with ".345" when t has milliseconds
fn rfc3339_local(t: float) str "2026-09-28T08:45:12+02:00" (the system's time zone)
fn parse_rfc3339(s: str) float
fn format(t: float, layout: str) str UTC
fn format_local(t: float, layout: str) str
fn parse(s: str, layout: str) float the fields are read as UTC
fn parse_local(s: str, layout: str) float
fn error() strRFC 3339 is the timestamp format of JSON APIs and logs. parse_rfc3339 accepts T or a space between date and time, any fraction of a second, and Z or a +hh:mm offset (an offset is required: a time without one is ambiguous). Layouts are C's strftime / strptime ones (%Y %m %d %H %M %S %j %A %B %Z, ...) plus %L for milliseconds and %f for microseconds, with English names on every system. parse reads the same directives: the whole input must match the whole layout ("Mar 18" doesn't match "%b %d %Y"), numbers may have spaces before them, %z (+0200, +02:00 or Z), %Z (UTC or GMT) and %s set the time, and weekday names and %j are read but don't. Fields the layout doesn't have are 1900-01-01 00:00:00. A parse that fails returns 0.0 and time.error() says why; after a success time.error() is "".
import time
fn main():
t = time.parse_rfc3339("2026-02-28T23:30:00.250-05:00")
print(time.rfc3339(t))
print(time.format(t, "%d %B %Y, %H:%M:%S.%L UTC"))
print(time.parse("28/09/2026 06:45", "%d/%m/%Y %H:%M") == time.parse_rfc3339("2026-09-28T06:45:00Z"))
bad = time.parse_rfc3339("2026-09-28 06:45:00")
print(bad, time.error())2026-03-01T04:30:00.250Z
01 March 2026, 04:30:00.250 UTC
true
0.0 not an RFC 3339 time: no time zone (Z or +hh:mm)Calendar fields and time zones
fn utc(t: float) Date
fn local(t: float) Date
fn date(year: int, month: int, day: int, hour: int, minute: int, second: int) float
fn offset(t: float) intDate has the fields year, month (1-12), day, hour, minute, second, nano (nanoseconds), weekday (0 is Sunday), yday (1-366) and offset (seconds east of UTC). local uses the system's time zone (the TZ environment variable, or the machine's setting), with daylight saving time. date builds a UTC time from fields; values out of range carry over, so month 13 is January of the next year and day 0 is the last day of the previous month, which makes calendar arithmetic simple:
import time
fn days_in_month(year: int, month: int) int:
return time.utc(time.date(year, month + 1, 0, 0, 0, 0)).day
fn main():
print(days_in_month(2024, 2), days_in_month(2026, 2), days_in_month(2026, 12))
d = time.utc(time.date(2026, 9, 28, 0, 0, 0))
print(d.weekday, d.yday)
next_week = time.date(2026, 9, 28 + 7, 0, 0, 0)
print(time.rfc3339(next_week))29 28 31
1 271
2026-10-05T00:00:00ZDurations
fn duration(seconds: float) str "1h2m3.5s", "250ms", "12us"
fn parse_duration(s: str) float "1h30m", "2.5s", "300ms", "-1m", "7d" -> secondsThe format Go uses (units h, m, s, ms, us, ns), plus days d (24h) and weeks w (7d), so a lookback like 7d or 2w can be written directly. parse_duration returns 0.0 and sets time.error() for text that isn't a duration (a bare number needs a unit).
import time
fn main():
start = time.mono_ns()
time.sleep(15)
took = float(time.mono_ns() - start) / 1e9
print(took >= 0.015)
print(time.duration(3723.5), time.duration(0.25))
print(time.parse_duration("1h30m"), time.parse_duration("300ms"), time.parse_duration("7d"))true
1h2m3.5s 250ms
5400.0 0.3 604800.0With Result
try_parse_rfc3339(s), try_parse(s, layout) and try_parse_duration(s) return Result[float, str]: t = time.try_parse_rfc3339(s)?. The error reads like "time: not an RFC 3339 time: yesterday".
A complete example
Timing a function over several runs and reporting the best and average times:
import time
import fmt
fn count_primes(n: int) int:
sieve = [true] * (n + 1)
count = 0
for i in 2..n + 1:
if sieve[i]:
count += 1
j = i * i
while j <= n:
sieve[j] = false
j += i
return count
fn main():
runs = 5
best = 1_000_000
total = 0
result = 0
for r in 0..runs:
t0 = time.now()
result = count_primes(200_000)
ms = int((time.now() - t0) * 1000.0)
total += ms
best = min(best, ms)
print("primes below 200,000:", result)
print(f"best {best} ms, average {fmt.fixed(float(total) / float(runs), 1)} ms")Its output depends on the machine, for example:
primes below 200,000: 17984
best 1 ms, average 1.2 ms