If you're new to Python, you've probably come across Unix timestamps like this:

1719820800

At first glance, it's just a number. In reality, it represents a specific point in time.

Converting a Unix timestamp to a readable date is a common task in Python, but many beginners get confused when they see two different approaches:

  • datetime.fromtimestamp()
  • pd.to_datetime()

Both can convert timestamps into dates, but they are designed for different use cases and may produce different results depending on how they're used.

In this guide, you'll learn when to use each method, how they differ, and the common mistakes to avoid.

What Is a Unix Timestamp?

A Unix timestamp represents the number of seconds that have elapsed since:

1970-01-01 00:00:00 UTC

For example:

1719820800

corresponds to:

2024-07-01 00:00:00 UTC

In practice, you'll usually encounter two formats:

Type Example
Seconds 1719820800
Milliseconds 1719820800000

Before converting a timestamp, always verify whether it's stored in seconds or milliseconds.

Converting a Timestamp with datetime.fromtimestamp()

If you're working with a single timestamp, Python's built-in datetime module is often the simplest solution.

from datetime import datetime

timestamp = 1719820800

dt = datetime.fromtimestamp(timestamp)

print(dt)

Output:

2024-07-01 08:00:00

Many beginners immediately ask:

Why is the result 08:00:00 instead of 00:00:00?

The reason is that:

datetime.fromtimestamp()

converts the timestamp into your local system time.

If your machine is configured for UTC+8 (such as Singapore, China, or Malaysia), then:

2024-07-01 00:00:00 UTC

becomes:

2024-07-01 08:00:00

in local time.

Getting UTC Time Instead

If you want the result in UTC, specify the timezone explicitly:

from datetime import datetime, timezone

timestamp = 1719820800

dt = datetime.fromtimestamp(
    timestamp,
    tz=timezone.utc
)

print(dt)

Output:

2024-07-01 00:00:00+00:00

This avoids any dependence on your system's local timezone settings.

Converting a Timestamp with Pandas

When working with datasets, Pandas is usually the preferred option.

import pandas as pd

timestamp = 1719820800

dt = pd.to_datetime(
    timestamp,
    unit="s"
)

print(dt)

Output:

2024-07-01 00:00:00

There are two important things to note here.

First, always specify the unit:

unit="s"

This tells Pandas that the value represents seconds.

Second, Pandas handles datetime conversion differently from datetime.fromtimestamp(), which is why the output may not match what you see from the standard library.

datetime vs Pandas: What's the Difference?

Although both methods can convert timestamps, they are intended for different scenarios.

Feature datetime.fromtimestamp() pd.to_datetime()
Library Python Standard Library Pandas
Extra Installation Required No Yes
Single Timestamp Conversion ✓ ✓
Bulk Conversion Limited ✓
DataFrame Integration No ✓
Data Analysis Workflows Limited ✓
Time Series Features Basic Advanced

A simple rule of thumb:

  • Use datetime for application logic and individual values.
  • Use Pandas for data processing and analysis.

Converting Multiple Timestamps

Suppose you have a list of timestamps:

timestamps = [
    1719820800,
    1719907200,
    1719993600
]

With datetime, you'll typically loop through the values:

from datetime import datetime

dates = [
    datetime.fromtimestamp(ts)
    for ts in timestamps
]

With Pandas, you can convert the entire list at once:

import pandas as pd

dates = pd.to_datetime(
    timestamps,
    unit="s"
)

print(dates)

Output:

DatetimeIndex([
    '2024-07-01',
    '2024-07-02',
    '2024-07-03'
], dtype='datetime64[ns]')

This becomes especially useful when working with large datasets.

Converting a Timestamp Column in a DataFrame

One of the most common real-world use cases is converting timestamp columns.

import pandas as pd

df = pd.DataFrame({
    "timestamp": [
        1719820800,
        1719907200
    ]
})

Convert the column:

df["date"] = pd.to_datetime(
    df["timestamp"],
    unit="s"
)

print(df)

Output:

    timestamp       date
0  1719820800 2024-07-01
1  1719907200 2024-07-02

This is cleaner and more efficient than looping through rows manually.

Seconds vs Milliseconds

Another common source of confusion is timestamp precision.

Many APIs return timestamps like:

1719820800000

Notice the extra three digits.

This is a millisecond timestamp.

If you write:

pd.to_datetime(
    1719820800000,
    unit="s"
)

you'll likely get an error such as:

OutOfBoundsDatetime

The correct approach is:

pd.to_datetime(
    1719820800000,
    unit="ms"
)

Or with datetime:

datetime.fromtimestamp(
    1719820800000 / 1000
)

A quick rule:

  • 10 digits → seconds
  • 13 digits → milliseconds

Common Mistakes Beginners Make

1. Forgetting to Specify the Unit

Incorrect:

pd.to_datetime(1719820800)

Pandas may interpret the number as nanoseconds, resulting in an unexpected date.

Correct:

pd.to_datetime(
    1719820800,
    unit="s"
)

2. Ignoring Time Zones

Many developers notice that:

datetime.fromtimestamp()

and:

pd.to_datetime()

appear to return different results.

In most cases, the discrepancy comes from timezone handling rather than the timestamp itself.

Whenever you're working with dates and times, it's a good idea to be explicit about:

  • The timezone of the source data
  • The timezone used for storage
  • The timezone used for display

3. Using datetime for Large Datasets

Code like this works:

for ts in timestamps:
    datetime.fromtimestamp(ts)

But it doesn't scale well when dealing with thousands or millions of records.

If your data is already in a DataFrame, using:

pd.to_datetime()

is usually faster and easier to maintain.

Which Method Should You Use?

Choose datetime.fromtimestamp() if you are:

  • Writing a simple script
  • Building backend logic
  • Converting individual timestamps
  • Avoiding external dependencies

Example:

from datetime import datetime

datetime.fromtimestamp(1719820800)

Choose pd.to_datetime() if you are:

  • Working with DataFrames
  • Processing CSV or Excel files
  • Performing data analysis
  • Handling large datasets
  • Building time-series workflows

Example:

df["date"] = pd.to_datetime(
    df["timestamp"],
    unit="s"
)

Final Thoughts

For Python beginners, the biggest source of confusion is that both datetime.fromtimestamp() and pd.to_datetime() can convert Unix timestamps, but they serve different purposes.

A simple way to remember the difference is:

Use datetime for application logic and Pandas for data processing.

Before converting any timestamp, always check:

  1. Is it in seconds or milliseconds?
  2. Does timezone handling matter?
  3. Am I converting a single value or an entire dataset?

Keeping these questions in mind will help you avoid most timestamp-related issues in Python. For quick timestamp conversions without writing code, try the FastUnix Timestamp Converter.