Tern

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)
Output
true true

now

fn now() float

The 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() int

The 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)
Output
true true
true
true

Both 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")
Output
tick 0
tick 1
tick 2
done

Monotonic clock

fn mono_ns() int
fn mono_ms() int

A 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() str

RFC 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())
Output
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) int

Date 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))
Output
29 28 31
1 271
2026-10-05T00:00:00Z

Durations

fn duration(seconds: float) str      "1h2m3.5s", "250ms", "12us"
fn parse_duration(s: str) float      "1h30m", "2.5s", "300ms", "-1m", "7d" -> seconds

The 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"))
Output
true
1h2m3.5s 250ms
5400.0 0.3 604800.0

With 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
Source: docs/std/time.md. Every example on this page is compiled and run by tern x test docs.