Time Conversions

Time conversion utilities exist between the four modes of time that we use in gnss_lib_py. The four are: 1. GPS Week since epoch start and time of week in seconds 2. GPS milliseconds since start of GPS Epoch 3. Unix milliseconds since start of unix epoch 4. Python datetime objects (timezone assumed to be UTC if none provided).

Functionality exists for all 12 combinations of conversions between the four time instances, but here we show just a few examples. Other functionality is available in gnss_lib_py/utils/time_conversions.py.

from datetime import datetime, timezone
import gnss_lib_py as glp

Methods to convert datetime to the other types of time instances.

time_now = datetime.now(tz=timezone.utc)
print(f'Datetime {time_now}')

# convert datetime to GPS week and GPS time of week
gps_week, gps_tow = glp.datetime_to_tow(time_now)
print(f"gps week: {gps_week} gps tow: {gps_tow}")

# convert datetime to GPS milliseconds
gps_millis = glp.datetime_to_gps_millis(time_now)
print(f"GPS milliseconds: {gps_millis}")

# convert datetime to UNIX milliseconds
unix_millis = glp.datetime_to_unix_millis(time_now)
print(f"UNIX milliseconds: {unix_millis}")

Datetime 2026-06-02 01:39:37.075463+00:00
gps week: 2421 gps tow: 178795.075463
GPS milliseconds: 1464399595075.4631
UNIX milliseconds: 1780364377075.4631

In many cases, the timezone attribute is required. If it is not present, conversion functions will assume that the timezone is UTC and add the timezone information after raising a warning.

local_time_without_tz = datetime.now()
print(f'Datetime without timezone {local_time_without_tz}')
gps_millis_without_tz = glp.datetime_to_gps_millis(local_time_without_tz)

print(f"GPS milliseconds without timezone: {gps_millis_without_tz}")

Datetime without timezone 2026-06-02 01:39:37.081932
GPS milliseconds without timezone: 1464399595081.9321

/home/docs/checkouts/readthedocs.org/user_builds/gnss-lib-py/envs/latest/lib/python3.9/site-packages/gnss_lib_py/utils/time_conversions.py:586: RuntimeWarning: No time zone info found in datetime, assuming UTC
  warnings.warn("No time zone info found in datetime, assuming UTC",\

As seen by the example above, datetime.now() returns time without time zone information but in the local time zone. Time converstion functions assume that this time is in UTC time zone even when it is not and users should be careful about what timezone their input time is in before converting it. To ensure that the correct time zone is being used, use the pytz module to assign the right time zone as shown below.

If you are using Python>=3.9, you can use the inbuilt zoneinfo.ZoneInfo class instead of pytz.timezone as well.

import pytz
local_time_without_tz = datetime.now()
local_time_with_tz = local_time_without_tz.replace(tzinfo=pytz.timezone("America/Los_Angeles"))
print('Datetime with timezone', local_time_with_tz)
gps_millis_local_time = glp.datetime_to_gps_millis(local_time_with_tz)
print(f"GPS milliseconds with local timezone: {gps_millis_local_time}")

Datetime with timezone 2026-06-02 01:39:37.089202-07:53
GPS milliseconds with local timezone: 1464427975089.202

Methods to convert GPS week and GPS time of week to the other types of time instances.

# convert GPS week and GPS time of week to datetime
datetime = glp.tow_to_datetime(gps_week, gps_tow)
print("datetime in UTC: ",datetime.strftime("%d %B, %Y %H:%M:%S"))

# convert GPS week and GPS time to GPS milliseconds
gps_millis = glp.tow_to_gps_millis(gps_week, gps_tow)
print(f"GPS milliseconds: {gps_millis}")

# convert GPS week and GPS time to UNIX milliseconds
unix_millis = glp.tow_to_unix_millis(gps_week, gps_tow)
print(f"UNIX milliseconds: {unix_millis}")

datetime in UTC:  02 June, 2026 01:39:37
GPS milliseconds: 1464399595075.4631
UNIX milliseconds: 1780364377075.4631

Methods to convert GPS milliseconds to other types of time instances.

# convert GPS milliseconds to datetime
datetime = glp.gps_millis_to_datetime(gps_millis)
print("datetime in UTC: ",datetime.strftime("%d %B, %Y %H:%M:%S"))

# convert GPS milliseconds to GPS week and GPS time
gps_week, gps_tow = glp.gps_millis_to_tow(gps_millis)
print(f"gps week: {gps_week} gps tow: {gps_tow}")

# convert GPS milliseconds to UNIX milliseconds
unix_millis = glp.gps_to_unix_millis(gps_millis)
print(f"UNIX milliseconds: {unix_millis}")

datetime in UTC:  02 June, 2026 01:39:37
gps week: 2421 gps tow: 178795.07546313477
UNIX milliseconds: 1780364377075.4631

Methods to convert UNIX milliseconds to other types of time instances.

# convert UNIX milliseconds to datetime
datetime = glp.unix_millis_to_datetime(unix_millis)
print("datetime in UTC: ",datetime.strftime("%d %B, %Y %H:%M:%S"))

# convert UNIX milliseconds to GPS week and GPS time
gps_week, gps_tow = glp.unix_millis_to_tow(unix_millis)
print(f"gps week: {gps_week} gps tow: {gps_tow}")

# convert GPS milliseconds to UNIX milliseconds
gps_millis = glp.unix_to_gps_millis(unix_millis)
print(f"GPS milliseconds: {gps_millis}")

datetime in UTC:  02 June, 2026 01:39:37
gps week: 2421 gps tow: 178795.075463
GPS milliseconds: 1464399595075.4631