datetime.fromtimestamp(timestamp, tz=None) converts a POSIX timestamp, the number of seconds since 1970-01-01 00:00:00 UTC, into a datetime. Floats are allowed, and the fraction becomes microseconds.
With tz=timezone.utc (or any tzinfo) the result is an aware datetime in that zone. Without tz it is a naive datetime in the machine's local time zone. It is the inverse of timestamp() and replaces the deprecated utcfromtimestamp().
datetime.fromtimestamp() is a classmethod of datetime.datetime: call it on the class itself, as datetime.fromtimestamp(...), and it returns a new object. Import the class first, for example from datetime import datetime. The date class has a method with the same name.
Syntax
Pass the number of seconds and, ideally, a time zone.
python
moment = datetime.fromtimestamp(timestamp)
moment = datetime.fromtimestamp(timestamp, tz=timezone.utc)
day = date.fromtimestamp(timestamp)
Call
What it does
datetime.fromtimestamp(0, tz=timezone.utc)
Returns datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc): the epoch.
Gives a naive datetime in the local time zone, so the result changes from one computer to another.
Leap seconds are not counted, and date.fromtimestamp(ts) only accepts a timestamp (no tz); it returns the local date.
Method signatures
python
classmethod datetime.fromtimestamp(timestamp, tz=None)
classmethod date.fromtimestamp(timestamp)
# timestamp: int or float seconds since the epoch (UTC)
# returns: datetime (aware if tz is given) / date
Parameters
Parameter
Description
timestamp
Seconds since 1970-01-01 00:00:00 UTC, as an int or float. Negative values are before 1970.
tz
Optional. A tzinfo for the result, such as timezone.utc. Default None gives naive local time.
Return Value
Return Value
Description
datetime
The moment the timestamp describes, aware in tz or naive local time.
Python Examples
Example 1 — Convert Timestamps to Aware UTC datetimes
Convert the epoch, one day later, and a 2024 timestamp. With tz=timezone.utc the output is identical on every machine.
python
from datetime import datetime, timezone
for ts in (0, 86400, 1710498645):
print(datetime.fromtimestamp(ts, tz=timezone.utc))
Zero is the epoch. Timestamp 0 is midnight on 1 January 1970 in UTC.
One day of seconds. 86400 seconds is exactly 24 hours, so the date moves to 2 January.
Aware output. Printing an aware datetime adds the offset +00:00 after the time.
Example 2 — Show One Timestamp in Three Zones
A float timestamp keeps its fraction as microseconds. Passing different tz values changes the wall-clock reading, not the instant.
python
from datetime import datetime, timedelta, timezone
ts = 1700000000.25
ist = timezone(timedelta(hours=5, minutes=30))
est = timezone(timedelta(hours=-5), "EST")
print(datetime.fromtimestamp(ts, tz=timezone.utc))
print(datetime.fromtimestamp(ts, tz=ist))
print(datetime.fromtimestamp(ts, tz=est).strftime("%Y-%m-%d %H:%M %Z"))
Output
2023-11-14 22:13:20.250000+00:00
2023-11-15 03:43:20.250000+05:30
2023-11-14 17:13 EST
How It Works
Fraction to microseconds. The .25 part of the timestamp becomes microsecond=250000, shown as .250000.
Past midnight in India. Adding 5 hours 30 minutes to 22:13 UTC moves the date to 15 November.
Named offset. The second argument of timezone() sets the name that strftime() prints for %Z.
Example 3 — Handle Millisecond Timestamps from APIs
JavaScript and many web APIs send milliseconds. Divide by 1000 first; passing the raw value fails because the year would be far beyond 9999.
python
from datetime import datetime, timezone
millis = 1718900000123
moment = datetime.fromtimestamp(millis / 1000, tz=timezone.utc)
print(moment.isoformat(timespec="milliseconds"))
try:
datetime.fromtimestamp(millis, tz=timezone.utc)
except (ValueError, OverflowError, OSError):
print("milliseconds passed as seconds: out of range")
Output
2024-06-20T16:13:20.123+00:00
milliseconds passed as seconds: out of range
How It Works
Scale first.millis / 1000 gives seconds as a float, and the fraction becomes 123 milliseconds after rounding to microseconds.
Readable check.isoformat() with timespec="milliseconds" prints three fractional digits.
Raw millis overflow. 1718900000123 seconds is tens of thousands of years away, so Python raises an error.
Catch all three. Depending on the platform the error is ValueError, OverflowError, or OSError, so the tuple covers them.
Frequently Asked Questions
Use datetime.fromtimestamp(ts, tz=timezone.utc). It returns an aware UTC datetime that is the same on every machine.
Without tz the result is in the computer's local time zone. Pass tz=timezone.utc to get UTC.
Divide by 1000 first: datetime.fromtimestamp(ms / 1000, tz=timezone.utc).
The C library on Windows rejects some values, especially negative timestamps. Use datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=ts) for those.
datetime.fromtimestamp(ts, tz=timezone.utc). It gives the same UTC fields but with the zone attached.