Python Timestamp to Datetime

Working with time in Python is common. You often get a timestamp. This is a number. It represents seconds since January 1, 1970. This is the Unix epoch. You need to convert it to a human-readable date. This guide shows you how.

We use the datetime module. It is a built-in module. No extra installation is needed. The key method is fromtimestamp(). This method converts a timestamp to a datetime object.

What is a Timestamp?

A timestamp is a single number. It counts seconds from the Unix epoch. For example, 1672531200 is a timestamp. It represents a specific moment in time. Computers use this format. It is simple and universal.

But humans prefer dates like "2023-01-01". Converting the number to a date is essential. This is where fromtimestamp() helps.

Using fromtimestamp()

The fromtimestamp() method is in the datetime class. You call it on the class itself. You pass the timestamp as an argument. It returns a datetime object.

Here is a basic example:

 
# Import the datetime module
from datetime import datetime

# Define a timestamp
timestamp = 1672531200

# Convert timestamp to datetime
dt_object = datetime.fromtimestamp(timestamp)

# Print the result
print(dt_object)

Output:

2023-01-01 00:00:00

The output is a datetime object. It shows the date and time. This is much easier to read than the number.

Understanding Time Zones

The fromtimestamp() method uses your local time zone. This is important. The same timestamp can show different times in different places. For example, London and New York see different local times.

If you need UTC time, use utcfromtimestamp(). This method returns a naive datetime in UTC. It ignores your local time zone.

 
from datetime import datetime

timestamp = 1672531200

# Convert to UTC
utc_dt = datetime.utcfromtimestamp(timestamp)

print(utc_dt)

Output:

2023-01-01 00:00:00

For this timestamp, local and UTC are the same. But this is not always true. Always be aware of time zones.

Handling Milliseconds

Some timestamps include milliseconds. For example, 1672531200123. This includes 123 milliseconds. The fromtimestamp() method can handle this. It accepts a float.

 
from datetime import datetime

# Timestamp with milliseconds
timestamp_ms = 1672531200123.0

# Convert to seconds by dividing by 1000
timestamp_sec = timestamp_ms / 1000.0

dt_object = datetime.fromtimestamp(timestamp_sec)

print(dt_object)

Output:

2023-01-01 00:00:00.123000

Notice the microseconds. Python's datetime supports microseconds. This is precise. You get a full datetime object with fractions of a second.

Converting to a String

After conversion, you may want a string. Use the strftime() method. This formats the datetime as a string. For more details, see our Python Datetime Strftime Guide.

 
from datetime import datetime

timestamp = 1672531200
dt_object = datetime.fromtimestamp(timestamp)

# Format as a string
formatted = dt_object.strftime("%Y-%m-%d %H:%M:%S")
print(formatted)

Output:

2023-01-01 00:00:00

You can change the format. Use different format codes. This gives you full control.

Parsing Strings Back to Timestamps

Sometimes you have a date string. You need the timestamp. Use strptime() to parse the string. Then use timestamp() to get the number. Check our Python Datetime Strptime Guide for more.

 
from datetime import datetime

date_string = "2023-01-01 00:00:00"
dt_object = datetime.strptime(date_string, "%Y-%m-%d %H:%M:%S")

# Convert to timestamp
timestamp = dt_object.timestamp()
print(timestamp)

Output:

1672531200.0

This is useful for data processing. You can convert back and forth easily.

Common Errors and Solutions

One common error is OverflowError. This happens with timestamps outside the supported range. Python supports years from 1 to 9999. If your timestamp is too large, you get an error.

Another error is TypeError. This occurs if you pass a string instead of a number. Always ensure your timestamp is an integer or float.

 
from datetime import datetime

# This will cause a TypeError
try:
    dt = datetime.fromtimestamp("1672531200")
except TypeError as e:
    print("Error:", e)

Output:

Error: an integer is required (got type str)

Always convert strings to numbers first. Use int() or float().

Working with Time Zones Properly

For production code, use timezone-aware objects. The pytz library is helpful. But Python 3.9+ has zoneinfo. This is built-in. It handles time zones correctly.

 
from datetime import datetime
from zoneinfo import ZoneInfo

timestamp = 1672531200

# Convert to a specific time zone
tz = ZoneInfo("America/New_York")
dt_ny = datetime.fromtimestamp(timestamp, tz=tz)

print(dt_ny)

Output:

2022-12-31 19:00:00-05:00

Notice the time is different. New York is behind UTC. This is accurate. Always use time zones for global applications.

Real-World Use Cases

Timestamps appear in many places. Log files use them. Databases store them. APIs return them. Converting to datetime is essential for analysis.

For example, you parse a server log. Each entry has a timestamp. You convert it to datetime. Then you sort by date. You filter by time range. This makes data analysis possible.

Another use case is data visualization. You plot data over time. The x-axis needs dates. Timestamps are not human-friendly. Convert them first.

Performance Considerations

Converting many timestamps can be slow. But Python is efficient for most tasks. For millions of conversions, consider using numpy or pandas. These libraries handle arrays of timestamps faster.

For a single timestamp, use fromtimestamp(). It is simple and fast. For bulk operations, use vectorized functions.

Conclusion

Converting a Python timestamp to datetime is straightforward. Use fromtimestamp() for local time. Use utcfromtimestamp() for UTC. Always handle time zones carefully. This skill is fundamental for any Python developer.

Remember to check your timestamp format. Ensure it is a number. Handle errors gracefully. With these tools, you can work with time data confidently.

For a complete overview of datetime operations, see our Master Python Datetime Guide. You can also learn more about formatting dates with the Python Datetime to String Guide.