The time.time_ns() resolution is 3 times better than the time.time() resolution on Linux and Windows.

Add six new "nanosecond" variants of existing functions to the time module: clock_gettime_ns() , clock_settime_ns() , monotonic_ns() , perf_counter_ns() , process_time_ns() and time_ns() . While similar to the existing functions without the _ns suffix, they provide nanosecond resolution: they return a number of nanoseconds as a Python int .

The os.stat_result structure has 3 fields for timestamps as nanoseconds ( int ): st_atime_ns , st_ctime_ns and st_mtime_ns .

This issue was already fixed for file modification time by adding the st_mtime_ns field to the os.stat() result, and by accepting nanoseconds in os.utime() . This PEP proposes to generalize the fix.

Nowadays, more and more databases and filesystems support storing times with nanosecond resolution.

Two programs "A" and "B" are running on the same system and use the system clock. The program A reads the system clock with nanosecond resolution and writes a timestamp with nanosecond resolution. The program B reads the timestamp with nanosecond resolution, but compares it to the system clock read with a worse resolution. To simplify the example, let's say that B reads the clock with second resolution. If that case, there is a window of 1 second while the program B can see the timestamp written by A as "in the future".

On Python microbenchmarks, it is common to see function calls taking less than 100 ns. A difference of a few nanoseconds might become significant.

A server is running for longer than 104 days. A clock is read before and after running a function to measure its performance to detect performance issues at runtime. Such benchmark only loses precision because of the float type used by clocks, not because of the clock resolution.

Five years ago, the PEP 410 proposed a large and complex change in all Python functions returning time to support nanosecond resolution using the decimal.Decimal type.

time.time() returns seconds elapsed since the UNIX epoch: January 1st, 1970. This function hasn't had nanosecond precision since May 1970 (47 years ago):

The problem is that the float type starts to lose nanoseconds after 104 days. Converting from nanoseconds ( int ) to seconds ( float ) and then back to nanoseconds ( int ) to check if conversions lose precision:

The Python time.time() function returns the current time as a floating-point number which is usually a 64-bit binary floating-point number (in the IEEE 754 format).

The clocks resolution of desktop and laptop computers is getting closer to nanosecond resolution. More and more clocks have a frequency in MHz, up to GHz for the CPU TSC clock.

A new nanosecond-returning flavor of these functions may be added later if an operating system exposes new functions providing better resolution.

Python has other time-returning functions. No nanosecond variant is proposed for these other functions, either because their internal resolution is greater or equal to 1 us, or because their maximum value is small enough to not lose precision. For example, the maximum value of time.clock_getres() should be 1 second.

Since the time.clock() function was deprecated in Python 3.3, no time.clock_ns() is added.

These functions are needed because they may return "large" timestamps, like time.time() which uses the UNIX epoch as reference, and so their float -returning variants are likely to lose precision at the nanosecond resolution.

For example, time.monotonic_ns() == int(time.monotonic() * 1e9) if monotonic() value is small enough to not lose precision.

These functions are similar to the version without the _ns suffix, but return a number of nanoseconds as a Python int .

This PEP adds six new functions to the time module:

Sub-nanosecond resolution time.time_ns() API is not theoretically future-proof: if clock resolutions continue to increase below the nanosecond level, new Python functions may be needed. In practice, the 1 nanosecond resolution is currently enough for all structures returned by all common operating systems functions. Hardware clocks with a resolution better than 1 nanosecond already exist. For example, the frequency of a CPU TSC clock is the CPU base frequency: the resolution is around 0.3 ns for a CPU running at 3 GHz. Users who have access to such hardware and really need sub-nanosecond resolution can however extend Python for their needs. Such a rare use case doesn't justify to design the Python standard library to support sub-nanosecond resolution. For the CPython implementation, nanosecond resolution is convenient: the standard and well supported int64_t type can be used to store a nanosecond-precise timestamp. It supports a timespan of -292 years to +292 years. Using the UNIX epoch as reference, it therefore supports representing times since year 1677 to year 2262: >>> 1970 - 2 ** 63 / (10 ** 9 * 3600 * 24 * 365.25) 1677.728976954687 >>> 1970 + 2 ** 63 / (10 ** 9 * 3600 * 24 * 365.25) 2262.271023045313

Modifying time.time() result type It was proposed to modify time.time() to return a different number type with better precision. The PEP 410 proposed to return decimal.Decimal which already exists and supports arbitrary precision, but it was rejected. Apart from decimal.Decimal , no portable real number type with better precision is currently available in Python. Changing the built-in Python float type is out of the scope of this PEP. Moreover, changing existing functions to return a new type introduces a risk of breaking the backward compatibility even if the new type is designed carefully.

Different types Many ideas of new types were proposed to support larger or arbitrary precision: fractions, structures or 2-tuple using integers, fixed-point number, etc. See also the PEP 410 for a previous long discussion on other types. Adding a new type requires more effort to support it, than reusing the existing int type. The standard library, third party code and applications would have to be modified to support it. The Python int type is well known, well supported, easy to manipulate, and supports all arithmetic operations such as dt = t2 - t1 . Moreover, taking/returning an integer number of nanoseconds is not a new concept in Python, as witnessed by os.stat_result and os.utime(ns=(atime_ns, mtime_ns)) . Note If the Python float type becomes larger (e.g. decimal128 or float128), the time.time() precision will increase as well.

Different API The time.time(ns=False) API was proposed to avoid adding new functions. It's an uncommon (and bad?) programming practice in Python to change the result type depending on a parameter. Different options were proposed to allow the user to choose the time resolution. If each Python module uses a different resolution, it can become difficult to handle different resolutions, instead of just seconds ( time.time() returning float ) and nanoseconds ( time.time_ns() returning int ). Moreover, as written above, there is no need for resolution better than 1 nanosecond in practice in the Python standard library.