Python datetime.timetuple() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
datetime method

Definition

timetuple() converts a date or datetime into a time.struct_time, the 9-field tuple used by the time module: year, month, day, hour, minute, second, weekday (Monday 0), day of the year (1 to 366), and a DST flag.

The tm_isdst flag is -1 when dst() returns None (naive values and fixed offsets), 1 when it returns a non-zero timedelta, and 0 otherwise. No time zone conversion happens; for UTC fields use utctimetuple().

datetime.timetuple() is an instance method of datetime.datetime: call it on an existing object with dot notation, such as moment.timetuple(...). Import the class first, for example from datetime import datetime. The date class has a method with the same name.

Syntax

Call it with no arguments and read the fields by name or index.

python
tt = moment.timetuple()
print(tt.tm_year, tt.tm_yday, tt.tm_isdst)
CallWhat it does
datetime(2024, 3, 15, 10, 30).timetuple().tm_ydayReturns 75: 31 + 29 + 15.
date(2024, 3, 15).timetuple().tm_hourReturns 0: dates have no time.
datetime(2024, 3, 15).timetuple().tm_isdstReturns -1: naive, DST unknown.

Microseconds are dropped, because struct_time has whole seconds only.

Method signatures
python
datetime.timetuple()
date.timetuple()
# returns: time.struct_time(tm_year, tm_mon, tm_mday, tm_hour, tm_min,
#                           tm_sec, tm_wday, tm_yday, tm_isdst)

Parameters

timetuple() takes no parameters.

Return Value

Return ValueDescription
time.struct_timeA named tuple of 9 ints; tm_wday uses Monday = 0 and tm_yday starts at 1.

Python Examples

Example 1 — Read the Fields of a struct_time

Convert one datetime and print the fields in three groups, then slice it like a tuple.

python
from datetime import datetime

tt = datetime(2024, 3, 15, 10, 30, 45).timetuple()
print(tt.tm_year, tt.tm_mon, tt.tm_mday)
print(tt.tm_hour, tt.tm_min, tt.tm_sec)
print(tt.tm_wday, tt.tm_yday, tt.tm_isdst)
print(tt[0:3])

How It Works

  1. Named fields. Every part has a tm_ name, which is clearer than an index.
  2. Derived values. tm_wday is 4 (Friday, counting Monday as 0) and tm_yday is 75.
  3. Unknown DST. The value is naive, so tm_isdst is -1.
  4. Still a tuple. Slicing the first three items gives a plain tuple of ints.

Example 2 — See How tm_isdst Follows dst()

Compare a naive value, a UTC value, and a toy zone with one hour of summer time from April to September.

python
from datetime import datetime, timedelta, timezone, tzinfo


class ToyZone(tzinfo):
    def utcoffset(self, dt):
        return timedelta(hours=1) + self.dst(dt)

    def dst(self, dt):
        return timedelta(hours=1) if 4 <= dt.month <= 9 else timedelta(0)

    def tzname(self, dt):
        return "TOY"


samples = [
    datetime(2024, 1, 10, 12, 0),
    datetime(2024, 1, 10, 12, 0, tzinfo=timezone.utc),
    datetime(2024, 1, 10, 12, 0, tzinfo=ToyZone()),
    datetime(2024, 7, 10, 12, 0, tzinfo=ToyZone()),
]
for moment in samples:
    print(moment.timetuple().tm_isdst)

How It Works

  1. Naive gives -1. Without a tzinfo there is no DST information at all.
  2. Fixed offsets give -1 too. timezone.utc.dst() returns None, so the flag stays unknown.
  3. Winter in the toy zone. In January dst() returns timedelta(0), so the flag is 0.
  4. Summer in the toy zone. In July dst() returns one hour, so the flag is 1.

Example 3 — Pass timetuple() to time.strftime()

Functions in the time module accept a struct_time. Print the day of the year next to a formatted date for three holidays (C/English locale).

python
import time
from datetime import date

holidays = [date(2024, 1, 1), date(2024, 7, 4), date(2024, 12, 25)]
for day in holidays:
    tt = day.timetuple()
    print(tt.tm_yday, time.strftime("%d %b", tt), tt.tm_hour)

How It Works

  1. Dates work too. date.timetuple() fills the time fields with zeros.
  2. Day of the year. 4 July is day 186 in leap year 2024, and 25 December is day 360.
  3. time module bridge. time.strftime() takes the struct_time directly, which helps with older APIs.

Frequently Asked Questions

A named tuple from the time module with 9 fields: year, month, day, hour, minute, second, weekday, day of year, and DST flag.
Use d.timetuple().tm_yday, or d.strftime("%j") for zero-padded text.
The value is naive, or its tzinfo is a fixed offset whose dst() returns None.
No, it keeps the wall-clock fields. Use utctimetuple() for UTC fields.
No. struct_time has whole seconds only.

Next: datetime.timetz()

Return the clock part of a datetime as a time object that keeps its tzinfo.

timetz() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful