Python datetime.fromtimestamp() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
classmethod

Definition

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)
CallWhat it does
datetime.fromtimestamp(0, tz=timezone.utc)Returns datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc): the epoch.
datetime.fromtimestamp(1710498645, timezone.utc)Returns datetime.datetime(2024, 3, 15, 10, 30, 45, tzinfo=datetime.timezone.utc).
datetime.fromtimestamp(ts)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

ParameterDescription
timestampSeconds since 1970-01-01 00:00:00 UTC, as an int or float. Negative values are before 1970.
tzOptional. A tzinfo for the result, such as timezone.utc. Default None gives naive local time.

Return Value

Return ValueDescription
datetimeThe 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))

How It Works

  1. Zero is the epoch. Timestamp 0 is midnight on 1 January 1970 in UTC.
  2. One day of seconds. 86400 seconds is exactly 24 hours, so the date moves to 2 January.
  3. 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"))

How It Works

  1. Fraction to microseconds. The .25 part of the timestamp becomes microsecond=250000, shown as .250000.
  2. Past midnight in India. Adding 5 hours 30 minutes to 22:13 UTC moves the date to 15 November.
  3. 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")

How It Works

  1. Scale first. millis / 1000 gives seconds as a float, and the fraction becomes 123 milliseconds after rounding to microseconds.
  2. Readable check. isoformat() with timespec="milliseconds" prints three fractional digits.
  3. Raw millis overflow. 1718900000123 seconds is tens of thousands of years away, so Python raises an error.
  4. 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.

Next: date.isocalendar()

Return the ISO 8601 (year, week, weekday) for a date.

isocalendar() →

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.

16 people found this page helpful