Convert Unix Time (Epoch Time) to and from datetime in Python
This article explains how to convert Unix time (also known as Epoch time or Posix time) to and from datetime objects, which represent dates and times in Python.
For a basic overview of the datetime module, see the following article:
Unix time is often used for file timestamps, such as file creation and modification times. You can obtain the current Unix time using time.time(). For more details, refer to:
- Get file timestamp in Python (os.stat, os.path.getmtime, and more)
- Get the current date and time in Python (datetime.now, date.today)
What is Unix time (Epoch time, Posix time)?
Unix time represents the number of seconds elapsed since the Unix epoch — 00:00:00 UTC (Coordinated Universal Time) on January 1, 1970. It is also referred to as Epoch time, Posix time, and other similar terms.
Unix time (also known as Epoch time, Posix time, seconds since the Epoch, or UNIX Epoch time) is a system for describing a point in time. It is the number of seconds that have elapsed since the Unix epoch, excluding leap seconds. The Unix epoch is 00:00:00 UTC on 1 January 1970 (an arbitrary date). Unix time - Wikipedia
Convert Unix time to datetime: fromtimestamp()
To work with dates and times in Python, use the datetime module.
To convert Unix time to a datetime object, use datetime.fromtimestamp() from the datetime module, passing the Unix time as an argument.
By default, it returns the local date and time according to the system's timezone settings. For example, if your machine is set to Japan Standard Time (JST), the conversion will account for the +9 hour offset.
When passing 0 as an argument:
import datetime
dt = datetime.datetime.fromtimestamp(0)
print(dt)
# 1970-01-01 09:00:00
print(type(dt))
# <class 'datetime.datetime'>
print(dt.tzinfo)
# None
By default, the function returns a naive datetime object, meaning its tzinfo attribute is set to None.
You can also provide a second argument, tz, to specify a time zone. This will return an aware datetime object with the time adjusted to the specified time zone.
dt_utc_aware = datetime.datetime.fromtimestamp(0, datetime.timezone.utc)
print(dt_utc_aware)
# 1970-01-01 00:00:00+00:00
print(dt_utc_aware.tzinfo)
# UTC
dt_jst_aware = datetime.datetime.fromtimestamp(0, datetime.timezone(datetime.timedelta(hours=9)))
print(dt_jst_aware)
# 1970-01-01 09:00:00+09:00
print(dt_jst_aware.tzinfo)
# UTC+09:00
Additionally, datetime.utcfromtimestamp() is available to directly obtain a UTC-based naive datetime object (with tzinfo set to None).
dt_utc_naive = datetime.datetime.utcfromtimestamp(0)
print(dt_utc_naive)
# 1970-01-01 00:00:00
print(dt_utc_naive.tzinfo)
# None
Convert datetime to Unix time: timestamp()
To convert a datetime object into Unix time, use the timestamp() method. The result is returned as a floating-point number (float).
Consider the datetime objects created in the examples above.
print(dt)
# 1970-01-01 09:00:00
print(dt.timestamp())
# 0.0
print(type(dt.timestamp()))
# <class 'float'>
If the datetime object is naive (tzinfo is None), the conversion is based on the system’s local timezone. If it is aware (has a defined tzinfo), the conversion uses the specified timezone.
Note that the object created by utcfromtimestamp() is naive in UTC, meaning tzinfo is None, so the result is different from other objects.
print(dt_utc_aware)
# 1970-01-01 00:00:00+00:00
print(dt_utc_aware.timestamp())
# 0.0
print(dt_jst_aware)
# 1970-01-01 09:00:00+09:00
print(dt_jst_aware.timestamp())
# 0.0
print(dt_utc_naive)
# 1970-01-01 00:00:00
print(dt_utc_naive.timestamp())
# -32400.0
If you do not need to handle time zones explicitly, you can generally ignore these details, as both fromtimestamp() and timestamp() work based on the local time settings by default.