 Computer Science Atlas
Code Review

Python 3 Examples: Unix Timestamp

April 27, 2021

Unix Timestamp

A Unix timestamp is the number of seconds that have passed (elapsed) since the epoch (January 1, 1970 at 00:00:00 UTC). It provides a way to express any date and time as a single number without having to worry about multiple unit components (like hours and minutes) and time zones (since it uses UTC).

Python 3 provides functions for working with timestamps based on the operating system's definition of "epoch," which may be different from Unix's definition. However, Windows and Unix-like systems such as Linux and macOS (10 and above) all use Unix's definition of epoch (i.e., 1970-01-01 00:00:00 UTC), so Python's timestamp functions are effectively Unix timestamp functions when they're called on these operating systems. This article assumes we're using one of these operating systems.

Current Unix Timestamp

Second Precision

In Python 3, we can get the Unix timestamp for the current time by using the built-in time module: 1 2 3 4 import time now = int( time.time() ) print( now )

The time.time() function by itself returns the Unix timestamp as a float, with any value to the right of the decimal point representing fractions of a second. However, Python does not make any guarantees about the exact level of precision of this number beyond whole seconds (the exact precision varies depending on the operating system). So in the example above, we convert it into an integer using the built-in int() function, which truncates floats toward zero (i.e., simply removes the fractional value for both positive and negative numbers).

Nanosecond Precision (Python 3.7 and Up)

On Python 3.7 and higher, we can get a guaranteed higher precision timestamp using the time.time_ns() function, which returns an integer representing the number of nanoseconds since the epoch. To get the current nanosecond precision timestamp, we can write: 1 2 3 4 import time now_ns = time.time_ns() print( now_ns )

Millisecond Precision (Python 3.7 and Up)

If we want millisecond precision, we can simply divide the nanosecond timestamp provided by time.time_ns() by 1,000 and then truncate: 1 2 3 4 import time now_ms = int( time.time_ns() / 1000 ) print( now_ms )

Convert datetime to Unix Timestamp

To convert a date and time specified in our operating system's local time zone, we can first create a datetime object representing the date and time and then convert it to a Unix timestamp using the .timestamp() method.

For example, to get the Unix timestamp (in UTC) for 2021-03-05 14:30:21 in the system's local time zone, we can write: 1 2 3 4 5 from datetime import datetime dt = datetime( 2021, 3, 5, 14, 30, 21 ) timestamp = int( dt.timestamp() ) print( timestamp )

On Python versions 3.2 and higher, we can use the timezone class to specify any time zone we want. For example, to convert a datetime specified in UTC, we can write: 1 2 3 4 5 6 # Python 3.2 or higher required from datetime import datetime, timezone dt = datetime( 2021, 3, 5, 14, 30, 21, tzinfo=timezone.utc ) timestamp = int( dt.timestamp() ) print( timestamp )

Convert Unix Timestamp to datetime

If we want to find out what date and time a specific Unix timestamp represents, we can convert the timestamp to a datetime object.

For example, to convert a Unix timestamp to a datetime in the system's local time zone, we can write: 1 2 3 4 5 from datetime import datetime timestamp = 1614983421 dt = datetime.fromtimestamp( timestamp ) print( dt )

On Python versions 3.2 and higher, we can use the timezone class to convert Unix timestamps into other time zones. For example, to get the UTC datetime corresponding to the Unix timestamp 1614954621, we can write: 1 2 3 4 5 6 # Python 3.2 or higher required from datetime import datetime, timezone timestamp = 1614954621 dt = datetime.fromtimestamp( timestamp, tz=timezone.utc ) print( dt )