Python Datetime Timestamp Explained

Working with time in Python is essential. You often need to convert dates to numbers. That is where the Python datetime timestamp comes in.

A timestamp is a number. It represents the seconds since January 1, 1970. This is called Unix time or epoch time. Python makes it easy to get and use timestamps.

This guide will teach you everything about Python datetime timestamp. You will learn how to get timestamps, convert them, and avoid common mistakes. Let's start.

What is a Timestamp?

A timestamp is a single number. It counts the seconds since the Unix epoch. The epoch is January 1, 1970, at 00:00:00 UTC.

Timestamps are universal. They ignore time zones. This makes them great for storing time data. You can always convert a timestamp back to a readable date.

Python uses the datetime module to work with timestamps. The timestamp() method converts a datetime object to a timestamp.

Getting the Current Timestamp

You can get the current timestamp easily. Use the datetime.now() method. Then call the timestamp() method on it.

Here is a simple example:

import datetime

# Get current datetime
now = datetime.datetime.now()

# Convert to timestamp
current_timestamp = now.timestamp()

print(current_timestamp)

1682345678.123456

This prints a float number. The integer part is seconds. The decimal part is microseconds.

For more details on getting the current time, read our Python datetime now: Get Current Date & Time guide.

Converting a Datetime Object to a Timestamp

You can convert any datetime object to a timestamp. Use the timestamp() method. This works for past and future dates.

import datetime

# Create a specific date
my_date = datetime.datetime(2023, 4, 24, 15, 30, 0)

# Convert to timestamp
my_timestamp = my_date.timestamp()

print(my_timestamp)

1682343000.0

The output is a float. It represents the number of seconds from the epoch to your date.

Important: The datetime object must be timezone-aware for accurate results. If it is naive, Python assumes it is local time.

Converting a Timestamp Back to a Datetime

You can reverse the process. Use the fromtimestamp() method. This converts a timestamp to a datetime object.

import datetime

# A timestamp value
timestamp = 1682343000.0

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

print(date_from_timestamp)

2023-04-24 15:30:00

This returns a local datetime. If you want UTC, use utcfromtimestamp().

import datetime

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

print(utc_date)

2023-04-24 15:30:00

Working with Time Zones

Timestamps are always in UTC. But datetime objects can have time zones. Use the pytz library or Python's zoneinfo.

Here is an example with time zone:

import datetime
import pytz

# Create a timezone-aware datetime
tz = pytz.timezone('US/Eastern')
aware_date = datetime.datetime(2023, 4, 24, 11, 30, 0, tzinfo=tz)

# Convert to timestamp
timestamp_aware = aware_date.timestamp()

print(timestamp_aware)

1682343000.0

This ensures your timestamp is accurate. Always use timezone-aware objects when possible.

If you need to parse strings into dates, check our Python datetime strptime: Parse Strings to Dates guide.

Common Mistakes with Timestamps

Beginners often make mistakes. Here are three common ones to avoid.

1. Using Naive Datetime Objects

Naive objects have no time zone. Python assumes local time. This can cause errors if you expect UTC.

import datetime

# Naive datetime
naive = datetime.datetime(2023, 4, 24, 15, 30, 0)
print(naive.timestamp())

This works, but the result depends on your system's time zone. Always use aware objects for consistency.

2. Confusing Timestamp with Milliseconds

Python timestamps are in seconds. Some systems use milliseconds. Multiply by 1000 to convert.

import datetime

# Get timestamp in seconds
seconds = datetime.datetime.now().timestamp()

# Convert to milliseconds
milliseconds = seconds * 1000

print(milliseconds)

1682345678123.456

3. Forgetting the Epoch

The epoch is January 1, 1970. Dates before this give negative timestamps. This is valid but can cause issues.

import datetime

# Date before epoch
old_date = datetime.datetime(1969, 12, 31, 23, 59, 59)
print(old_date.timestamp())

-1.0

Formatting Timestamps into Strings

You can format timestamps into readable strings. First, convert to datetime. Then use strftime().

import datetime

# Get current timestamp
ts = datetime.datetime.now().timestamp()

# Convert to datetime
dt = datetime.datetime.fromtimestamp(ts)

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

print(formatted)

2023-04-24 15:30:00

For more formatting options, see our Python Datetime Strftime Guide.

Using Timestamps in Real Projects

Timestamps are useful for logging, databases, and APIs. They are easy to store and compare.

Here is a real example. Measure how long a function takes.

import datetime
import time

# Start time
start = datetime.datetime.now().timestamp()

# Simulate work
time.sleep(2)

# End time
end = datetime.datetime.now().timestamp()

# Calculate duration
duration = end - start
print(f"Function took {duration} seconds")

Function took 2.001234 seconds

This is simple and effective. You can log timestamps to track events.

Conclusion

The Python datetime timestamp is a powerful tool. It converts dates to numbers for easy storage and comparison.

Remember these key points:

• Use the timestamp() method to convert datetime to timestamp.
• Use fromtimestamp() to convert back.
• Always use timezone-aware objects for accuracy.
• Timestamps are in seconds since the Unix epoch.

Now you can handle timestamps with confidence. Practice with your own dates and times. For more datetime techniques, explore our Master Python Datetime Guide.