Introduction

Epoch time is a count of elapsed seconds from 1970-01-01 00:00:00 UTC. Converting it into a readable datetime is straightforward, but many bugs come from using the wrong unit, the wrong timezone, or the wrong API for local versus UTC output.

Know Whether the Number Is Seconds, Milliseconds, or More

The first question is not how to convert the timestamp. It is what the number means.

These values represent different units:

• '1700000000 is roughly seconds since the Unix epoch'
• '1700000000000 is roughly milliseconds'
• '1700000000000000 is roughly microseconds'

If you treat milliseconds as seconds, you will get a date far in the future or an out-of-range error.

Convert Epoch Time in Python

Python's datetime module is enough for most conversions. Use datetime.fromtimestamp for local time and datetime.utcfromtimestamp or a timezone-aware variant for UTC.

1from datetime import datetime, timezone
2
3epoch_seconds = 1700000000
4
5local_dt = datetime.fromtimestamp(epoch_seconds)
6utc_dt = datetime.fromtimestamp(epoch_seconds, tz=timezone.utc)
7
8print(local_dt)
9print(utc_dt)

If your input is in milliseconds, divide by 1000 first:

1from datetime import datetime, timezone
2
3epoch_millis = 1700000000000
4utc_dt = datetime.fromtimestamp(epoch_millis / 1000, tz=timezone.utc)
5
6print(utc_dt.isoformat())

That produces a timezone-aware datetime, which is usually safer than a naive one.

Convert to a Specific Time Zone

UTC is a good storage format, but applications often need local display. In modern Python, zoneinfo is the standard way to do that.

1from datetime import datetime, timezone
2from zoneinfo import ZoneInfo
3
4epoch_seconds = 1700000000
5utc_dt = datetime.fromtimestamp(epoch_seconds, tz=timezone.utc)
6toronto_dt = utc_dt.astimezone(ZoneInfo("America/Toronto"))
7
8print("UTC:", utc_dt.isoformat())
9print("Toronto:", toronto_dt.isoformat())

This is better than manually subtracting hours because daylight saving rules are handled for you.

Parse Many Values Safely

If you are processing logs or CSV files, add a unit check instead of assuming every input is seconds.

1from datetime import datetime, timezone
2
3def parse_epoch(value: int) -> datetime:
4    if value > 10**14:
5        value = value / 1_000_000
6    elif value > 10**11:
7        value = value / 1_000
8    return datetime.fromtimestamp(value, tz=timezone.utc)
9
10samples = [1700000000, 1700000000000, 1700000000000000]
11for sample in samples:
12    print(sample, "->", parse_epoch(sample).isoformat())

That kind of guard prevents silent data corruption when timestamps come from multiple systems.

Convert in SQL and JavaScript Too

If the source data is not in Python, the same concept still applies.

In PostgreSQL:

SELECT to_timestamp(1700000000);

For milliseconds in PostgreSQL:

SELECT to_timestamp(1700000000000 / 1000.0);

In JavaScript, the Date constructor expects milliseconds:

const epochSeconds = 1700000000;
const date = new Date(epochSeconds * 1000);
console.log(date.toISOString());

That difference is worth remembering because Python often works with seconds while JavaScript often works with milliseconds.

Formatting the Result

Readable output matters just as much as conversion. In Python, isoformat() is a good default because it is unambiguous.

1from datetime import datetime, timezone
2
3value = 1700000000
4dt = datetime.fromtimestamp(value, tz=timezone.utc)
5
6print(dt.isoformat())
7print(dt.strftime("%Y-%m-%d %H:%M:%S %Z"))

Use ISO 8601 for APIs and logs. Use strftime only when you need a human-facing format.

Why Time Zone Awareness Matters

A naive datetime has no timezone attached. That is fine for quick printing, but it becomes dangerous when values move between systems or get compared to timezone-aware values.

A better rule is:

• store and compare in UTC
• attach a timezone explicitly
• convert to local time only at presentation time

That keeps business logic predictable.

Common Pitfalls

Treating milliseconds as seconds. This is the most common cause of obviously wrong output.

Using local time when you expected UTC. fromtimestamp without a timezone argument uses the local machine's timezone.

Creating naive datetimes and comparing them with aware datetimes. Python will either raise or produce confusing code paths.

Hard-coding timezone offsets. Use zoneinfo instead of subtracting a fixed number of hours.

Formatting before you normalize the timezone. Convert first, then render the string.

Summary

• Epoch time is usually stored as seconds since 1970-01-01 00:00:00 UTC.
• Always confirm whether the input is seconds, milliseconds, or microseconds.
• In Python, prefer timezone-aware conversions with timezone.utc.
• Use zoneinfo for local display instead of manual hour offsets.
• For APIs and logs, isoformat() is usually the safest output format.