Introduction to Timestamps in Python

Python provides powerful, built-in modules to handle Unix timestamps. The most common are `time` and `datetime`. A Unix timestamp, representing seconds since the epoch (Jan 1, 1970), is a floating-point number in Python, which allows for sub-second precision.

1. Convert Unix Timestamp to a Readable Date

The most common task is converting a numeric timestamp into a human-readable date and time. The `datetime.fromtimestamp()` method is perfect for this.

python

import datetime

# The Unix timestamp (seconds since epoch)
timestamp = 1678886400

# Convert to a datetime object
date_object = datetime.datetime.fromtimestamp(timestamp)

print(f"Timestamp: {timestamp}")
print(f"Date Object: {date_object}")

# Format it into a readable string
readable_date = date_object.strftime("%Y-%m-%d %H:%M:%S")
print(f"Readable Date: {readable_date}")
# Expected Output: Readable Date: 2023-03-15 13:20:00 (if your local timezone is UTC+0)

2. Convert a Date to a Unix Timestamp

To perform the reverse operation, you can create a `datetime` object and then call the `.timestamp()` method on it.

python

import datetime

# Create a specific date
my_date = datetime.datetime(2024, 10, 12, 10, 30, 0)

# Convert the datetime object to a Unix timestamp
unix_timestamp = my_date.timestamp()

print(f"Date: {my_date}")
print(f"Unix Timestamp: {unix_timestamp}")
# Expected Output: Unix Timestamp: 1728712200.0

3. Get the Current Unix Timestamp

To get the current time as a Unix timestamp, use the `time.time()` function. It returns the number of seconds since the epoch as a float.

python

import time

# Get the current timestamp
current_timestamp = time.time()

print(f"Current Unix Timestamp: {current_timestamp}")

4. Handling Milliseconds

Some systems, especially in web development (like JavaScript), use millisecond-precision timestamps. Python's \`fromtimestamp\` and \`.timestamp()\` methods work with seconds, so you'll need to divide or multiply by 1000.

From Milliseconds to Datetime

python

import datetime

# Timestamp in milliseconds
ms_timestamp = 1678886400123

# Convert to seconds by dividing by 1000
s_timestamp = ms_timestamp / 1000

date_object = datetime.datetime.fromtimestamp(s_timestamp)

print(f"Date from Milliseconds: {date_object.strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]}")
# Expected Output: Date from Milliseconds: 2023-03-15 13:20:00.123

From Datetime to Milliseconds

python

import datetime

my_date = datetime.datetime.now()

# Get timestamp in seconds and multiply by 1000
ms_timestamp = my_date.timestamp() * 1000

print(f"Timestamp in Milliseconds: {int(ms_timestamp)}")

5. A Note on Timezones

By default, `datetime.fromtimestamp()` converts the timestamp to your system's **local timezone**. This is a very common source of confusion. To handle timezones correctly and explicitly, it's best practice to work with UTC.

python

import datetime

timestamp = 1678886400

# Convert to a timezone-aware datetime object in UTC
utc_date = datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)

print(f"UTC Date: {utc_date.strftime('%Y-%m-%d %H:%M:%S %Z')}")
# Expected Output: UTC Date: 2023-03-15 13:20:00 UTC

For more complex timezone operations, especially involving historical timezone changes, using a third-party library like `pytz` or `dateutil` is highly recommended.

🔗 Related Guides