datetime.timetuple / utctimetuple

The bridge to the older time module (time.mktime, calendar.timegm, time.strftime). Microseconds and the offset do not survive; tm_isdst says what dst() said.

date / datetime methodPython 2.3+Live demo
Common call
dt.timetuple().tm_yday
Returns
day of the year, 1..366
Replaces
Manual day-of-year arithmetic
Watch out
utctimetuple() on a NAIVE value does no conversion at all
dt.timetuple()
→ time.struct_time

Demo

Live evaluation
The local fields and the UTC fields of one timestamp.
Try:
Inputs
whenstran ISO 8601 timestamp
Code
from datetime import datetime
dt = datetime.fromisoformat('2026-09-29T01:30+02:00')
local, utc = dt.timetuple(), dt.utctimetuple()
(local.tm_hour, local.tm_isdst, utc.tm_mday, utc.tm_hour, utc.tm_isdst, local.tm_yday)
Result
(1, -1, 28, 23, 0, 272)

01:30+02:00 is 23:30 UTC on the previous day, so the UTC tuple shows day 28, hour 23. For a naive value utctimetuple() just copies the fields. tm_isdst is -1 (unknown) because timezone.dst() returns None, and always 0 in utctimetuple().

Common patterns

Day of the year
tm_yday, 1-based.
day_of_year = d.timetuple().tm_yday
UTC epoch seconds via calendar.timegm
The time-module route; dt.timestamp() is simpler for aware values.
import calendar
epoch = calendar.timegm(aware_dt.utctimetuple())

Examples

1. A date as struct_time
from datetime import date date(2026, 9, 29).timetuple()
Returns
time.struct_time(tm_year=2026, tm_mon=9, tm_mday=29, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=1, tm_yday=272, tm_isdst=-1)
2. Day of the year
from datetime import date date(2026, 9, 29).timetuple().tm_yday
Returns
272
3. utctimetuple converts aware values
from datetime import datetime, timedelta, timezone datetime(2026, 9, 29, 14, 30, tzinfo=timezone(timedelta(hours=2))).utctimetuple()
Returns
time.struct_time(tm_year=2026, tm_mon=9, tm_mday=29, tm_hour=12, tm_min=30, tm_sec=0, tm_wday=1, tm_yday=272, tm_isdst=0)
4. calendar.timegm on it
import calendar from datetime import datetime, timedelta, timezone calendar.timegm(datetime(2026, 9, 29, 14, 30, tzinfo=timezone(timedelta(hours=2))).utctimetuple())
Returns
1790685000
5. Indexable like a tuple
from datetime import date date(2026, 9, 29).timetuple()[:3]
Returns
(2026, 9, 29)

Pitfalls

1. Expecting microseconds
struct_time has whole seconds only; the fraction is dropped.
timetuple()
from datetime import datetime
datetime(2026, 9, 29, 14, 30, 5, 999999).timetuple().tm_sec
5
keep the datetime
from datetime import datetime
dt = datetime(2026, 9, 29, 14, 30, 5, 999999)
(dt.second, dt.microsecond)
(5, 999999)
2. tm_wday is Monday = 0, not Sunday = 0
It follows date.weekday(), unlike C's struct tm and strftime %w.
assume Sunday-first
from datetime import date
['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][date(2026, 9, 29).timetuple().tm_wday]
'Mon'
Monday-first
from datetime import date
['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'][date(2026, 9, 29).timetuple().tm_wday]
'Tue'

When to use

Use it
  • APIs of the time and calendar modules
  • tm_yday for the day of the year
Reach for something else
  • Anything the datetime object can do itself (strftime, timestamp, weekday)

Notes

CPython impl
build_struct_time in Modules/_datetimemodule.c; tm_isdst is -1 when dst() is None, 1 when dst() is non-zero, 0 otherwise
utctimetuple
Aware: subtracts utcoffset() first (may raise OverflowError at the range edges). Naive: fields unchanged. tm_isdst is always 0
date
date.timetuple() has zero time fields and tm_isdst -1

FAQ

d.timetuple().tm_yday (1 for 1 January), or d.strftime("%j") for the zero-padded string. You can also compute d.toordinal() - date(d.year, 1, 1).toordinal() + 1.