Home Python Datetime Methods toordinal() Python date.toordinal() Method Definition toordinal() returns the proleptic Gregorian ordinal of the date: day 1 is 0001-01-01, day 2 is 0001-01-02, and so on. 2024-01-01 is day 738886.
On a datetime it ignores the time and the zone and numbers only the date part. fromordinal() turns the number back into a date.
date.toordinal() is an instance method of datetime.date: call it on an existing object with dot notation, such as day.toordinal(...). Import the class first, for example from datetime import date. The datetime class has a method with the same name.
Syntax Call it with no arguments.
Call What it does date(1, 1, 1).toordinal()Returns 1. date(2024, 1, 1).toordinal()Returns 738886. date(1970, 1, 1).toordinal()Returns 719163: the Unix epoch day.
Ordinals are plain ints, so you can store them compactly, sort them, and subtract them.
Method signatures date.toordinal()
datetime.toordinal()
# returns: int, 1 .. 3652059 Parameters toordinal() takes no parameters.
Return Value Return Value Description int The day number, from 1 for 0001-01-01 to 3652059 for 9999-12-31.
Python Examples 1. Day numbers 2. Day differences 3. Weekday from ordinal Example 1 — Get the Day Number of a Date Number the first supported day, New Year 2024, and a datetime late on the same day.
from datetime import date, datetime
print(date(1, 1, 1).toordinal())
print(date(2024, 1, 1).toordinal())
print(datetime(2024, 1, 1, 23, 59).toordinal()) How It Works Counting starts at 1. The very first date in the calendar is day 1.Large but exact. 2024-01-01 is 738886 days into the count.Time ignored. A datetime at 23:59 on the same day gets the same ordinal.Example 2 — Count Days Between Two Dates Subtract ordinals and compare with date subtraction. February has 29 days in 2024 and 28 in 2023.
from datetime import date
start = date(2024, 2, 1)
end = date(2024, 3, 1)
print(end.toordinal() - start.toordinal())
print((end - start).days)
print(date(2023, 3, 1).toordinal() - date(2023, 2, 1).toordinal()) How It Works Ordinal subtraction. The difference of two ordinals is the number of days between them.Same as timedelta. (end - start).days gives the identical count.Leap years handled. February 2023 has 28 days, February 2024 has 29.Example 3 — Derive the Weekday from the Ordinal Day 1 was a Monday, so the ordinal modulo 7 encodes the weekday.
from datetime import date
day = date(2024, 3, 15)
n = day.toordinal()
print(n)
print(n % 7, day.isoweekday() % 7)
print((n + 6) % 7 == day.weekday()) How It Works Monday start. Ordinal 1 was a Monday, so n % 7 matches isoweekday() % 7 (Sunday becomes 0).Friday check. 738960 leaves remainder 5, and Friday's ISO number is 5.weekday() formula. (n + 6) % 7 is exactly how weekday() is defined.Frequently Asked Questions What is date.toordinal() used for? It turns a date into a simple day count, which is easy to store, compare, and subtract.
What is the ordinal of 1970-01-01? 719163.
How do I convert an ordinal back to a date? Use date.fromordinal(n).
Does toordinal() include the time of a datetime? No. Only the date part is counted.
Is toordinal() the same as a Unix timestamp? No. It counts days from year 1; a timestamp counts seconds from 1970. Day number minus 719163 gives days since the epoch.
Next: timedelta.total_seconds() Return the whole length of a timedelta in seconds, as a float.
total_seconds() → About the author Developer, cloud engineer, and technical writer
I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.
11 people found this page helpful
Helpful Share Copy link Suggestion