Home Python Datetime Methods utcfromtimestamp() Python datetime.utcfromtimestamp() Method Definition datetime.utcfromtimestamp(timestamp) converts seconds since the epoch into a datetime whose fields are in UTC , but returns it naive (tzinfo is None). For example, timestamp 0 gives 1970-01-01 00:00:00.
Python 3.12 deprecated it, so calls emit a DeprecationWarning. Use datetime.fromtimestamp(ts, tz=timezone.utc) from fromtimestamp() , which returns the same fields with UTC attached.
datetime.utcfromtimestamp() is a classmethod of datetime.datetime: call it on the class itself, as datetime.utcfromtimestamp(...), and it returns a new object. Import the class first, for example from datetime import datetime. It still works in current versions, but new code should use the aware replacement.
Syntax The deprecated call and the replacement side by side:
legacy = datetime.utcfromtimestamp(ts) # deprecated, naive
moment = datetime.fromtimestamp(ts, tz=timezone.utc) # recommended, aware Call What it does datetime.utcfromtimestamp(0)Returns datetime.datetime(1970, 1, 1, 0, 0): naive, no zone. datetime.utcfromtimestamp(1710498645)Returns datetime.datetime(2024, 3, 15, 10, 30, 45). datetime.fromtimestamp(1710498645, tz=timezone.utc)Returns datetime.datetime(2024, 3, 15, 10, 30, 45, tzinfo=datetime.timezone.utc): the replacement.
The DeprecationWarning goes to stderr and is hidden by default in imported modules; the return value is unchanged.
Method signatures classmethod datetime.utcfromtimestamp(timestamp)
# deprecated since Python 3.12
# returns: naive datetime with UTC fields Parameters Parameter Description timestamp Seconds since 1970-01-01 00:00:00 UTC, int or float.
Return Value Return Value Description datetime A naive datetime holding the UTC date and time of the timestamp.
Python Examples 1. What it returns 2. Old vs new 3. Fix stored values Example 1 — Convert the Epoch with utcfromtimestamp() Convert timestamp 0 and look at the printed value, the zone, and the full repr. Python 3.12+ also writes a DeprecationWarning to stderr.
from datetime import datetime
moment = datetime.utcfromtimestamp(0)
print(moment)
print(moment.tzinfo)
print(repr(moment)) 1970-01-01 00:00:00
None
datetime.datetime(1970, 1, 1, 0, 0) On Python 3.12+ a DeprecationWarning is also written to stderr; it is not shown in the stdout output above.
How It Works UTC fields. The fields are those of the epoch in UTC, whatever the local time zone is.Naive object. tzinfo is None, so no offset is printed after the time.Short repr. repr() drops trailing zero seconds and microseconds and shows no tzinfo= part.Example 2 — Compare the Deprecated Call with the Replacement Silence the warning for the old call, then compare its naive result with the aware replacement.
import warnings
from datetime import datetime, timezone
ts = 1710498645
with warnings.catch_warnings():
warnings.simplefilter("ignore", DeprecationWarning)
legacy = datetime.utcfromtimestamp(ts)
modern = datetime.fromtimestamp(ts, tz=timezone.utc)
print(legacy)
print(modern)
print(legacy == modern.replace(tzinfo=None))
print(legacy == modern) 2024-03-15 10:30:45
2024-03-15 10:30:45+00:00
True
False How It Works Scoped silence. warnings.catch_warnings() ignores the DeprecationWarning only inside the with block.Same clock fields. Both lines show 10:30:45 on 15 March 2024; only the modern value prints +00:00.Strip to compare. Removing the zone from the modern value makes it identical to the legacy one.Naive is never equal to aware. Comparing the two directly with == gives False instead of raising.Example 3 — Make Old Naive UTC Values Aware Rows saved by old code hold naive UTC datetimes. Attach UTC, then convert for display at UTC+05:30.
from datetime import datetime, timedelta, timezone
legacy_rows = [datetime(2024, 1, 1, 0, 0), datetime(2024, 6, 30, 18, 45)]
ist = timezone(timedelta(hours=5, minutes=30))
for naive in legacy_rows:
aware = naive.replace(tzinfo=timezone.utc)
print(aware.isoformat(), "->", aware.astimezone(ist).strftime("%d %b %H:%M")) 2024-01-01T00:00:00+00:00 -> 01 Jan 05:30
2024-06-30T18:45:00+00:00 -> 01 Jul 00:15 How It Works Known meaning. The rows came from utcfromtimestamp(), so their numbers are UTC even though no zone is stored.Label, do not shift. replace(tzinfo=timezone.utc) attaches UTC without moving the clock reading.Then convert. astimezone() shifts to UTC+05:30; 18:45 UTC on 30 June becomes 00:15 on 1 July.Month names. %b prints Jan and Jul under the default C/English locale.Frequently Asked Questions Is datetime.utcfromtimestamp() deprecated? Yes, since Python 3.12. Calls emit a DeprecationWarning.
What replaces utcfromtimestamp()? datetime.fromtimestamp(ts, tz=timezone.utc). It returns an aware datetime with the same UTC fields.
How do I get exactly the old naive result? Call datetime.fromtimestamp(ts, tz=timezone.utc).replace(tzinfo=None).
Why is a naive UTC datetime dangerous? Python treats naive values as local time in timestamp() and astimezone(), so the result is shifted by your UTC offset.
Does utcfromtimestamp() depend on my time zone? No, its fields are always UTC. Only later operations on the naive result depend on the local zone.
Next: datetime.utcoffset() Return the offset from UTC as a timedelta, or None for naive values.
utcoffset() → 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.
14 people found this page helpful
Helpful Share Copy link Suggestion