Python 3: Unix Timestamp

Create demo and training videos easily with Video Folder for macOS!

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.

In Python 3, we can get the Unix timestamp for the current time by using the built-in time module:

import time

now = int( time.time() )
print( now )

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).

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:

import time

now_ns = time.time_ns()
print( now_ns )

1
2
3
4

import time

now_ns = time.time_ns()
print( now_ns )

If we want millisecond precision, we can simply divide the nanosecond timestamp provided by time.time_ns() by 1,000 and then truncate:

import time

now_ms = int( time.time_ns() / 1000 )
print( now_ms )

1
2
3
4

import time

now_ms = int( time.time_ns() / 1000 )
print( now_ms )

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:

from datetime import datetime

dt = datetime( 2021, 3, 5, 14, 30, 21 )
timestamp = int( dt.timestamp() )
print( timestamp )

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:

# 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 )

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 )

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:

from datetime import datetime

timestamp = 1614983421
dt = datetime.fromtimestamp( timestamp )
print( dt )

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:

# Python 3.2 or higher required
from datetime import datetime, timezone

timestamp = 1614954621
dt = datetime.fromtimestamp( timestamp, tz=timezone.utc )
print( dt )

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 )

• time — Time access and conversions — Python 3 documentation
• datetime — Basic date and time types — Python 3 documentation

Create demo and training videos easily with Video Folder for macOS!