A Unix timestamp is a number that represents an instant by counting from 1970-01-01 00:00:00 UTC, the Unix epoch. The number is usually measured in seconds, but some systems—especially web APIs—use milliseconds. Check the unit before converting: reading milliseconds as seconds produces a wildly different date.
What is a Unix timestamp?
A timestamp is a numeric representation of an instant relative to a fixed starting point, called an epoch. In Unix and POSIX conventions, that starting point is midnight at the beginning of January 1, 1970, in UTC. The Python time-module documentation defines the epoch as the point returned by time.gmtime(0) and gives that same UTC date and time on all platforms: Python time documentation.
As an Amazon Associate I earn from qualifying purchases.
A conventional POSIX timestamp counts seconds from the epoch. A value of 0 is the epoch itself; 1 is one second after it. Some interfaces also represent fractional seconds, while others use a different base unit. The timestamp is not a formatted date and does not contain a time-zone label by itself—it is a numeric way to identify an instant.
Recommended Free Tools
Is a Unix timestamp in seconds or milliseconds?
It depends on the API or data source. Python’s time.time() returns seconds since the epoch as a floating-point number. The web-platform convention described by MDN uses milliseconds. Treat the unit as part of the data contract rather than guessing from the digits.
#1 Best Overall
- Seconds: pass the value directly to seconds-based functions such as Python’s
time.gmtime(). - Milliseconds: divide by
1000before passing it to a seconds-based function. - Fractional seconds: preserve the fraction if the receiving API supports it; otherwise, check how that API rounds or truncates.
For example, interpreting 1700000000000 as seconds instead of milliseconds does not mean “the same date with more precision”; it changes the represented instant by a factor of 1,000. MDN’s overview of Unix time describes the millisecond convention used by the web platform: MDN: Unix time.
How do I convert a Unix timestamp to a date in Python?
Use time.gmtime() for a UTC calendar breakdown and time.localtime() for the machine’s local time zone. The returned fields describe the same instant; the displayed clock time can differ because of the zone and its daylight-saving rules.
import time
seconds = 1_700_000_000
print(time.gmtime(seconds)) # UTC struct_time
print(time.localtime(seconds)) # machine-local struct_time
print(time.time()) # current epoch seconds, as a floatFor a millisecond input, convert units first:
milliseconds = 1_700_000_000_000
seconds = milliseconds / 1000
print(time.gmtime(seconds))To go in the other direction, Python provides calendar.timegm() for converting a UTC struct_time to seconds since the epoch. time.mktime() converts local-time fields, so it is not interchangeable when the input fields are meant to be UTC. Python also notes that supported date ranges and clock precision can depend on the underlying platform and C library; an out-of-range conversion may raise an error. See the Python time-module documentation.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsHow do I convert epoch time to UTC in a shell?
On systems with GNU date, prefix the seconds value with @ and add -u to request UTC output:
date -u -d '@1700000000'GNU documents @0 as 1970-01-01 00:00:00 UTC, @1 as the following second, and @-1 as the preceding second. GNU date‘s -d option is not available in every implementation of the date command, so these exact examples are for GNU systems. See GNU: Seconds since the Epoch.
When is GNU Awk useful for timestamps?
GNU Awk can convert textual date/time fields to a timestamp with mktime() and format a timestamp with strftime(). Those functions are useful in scripts that need to parse, compare, or reformat log times. GNU Awk’s time functions are documented in its Time Functions guide.
Why can the same timestamp show different dates?
The number identifies an instant, but the calendar display depends on the output time zone. UTC provides a consistent reference for logs and APIs; local time is appropriate when displaying a date to someone in a particular location. Python makes this distinction explicit: gmtime() converts to UTC fields, while localtime() converts using the machine’s local zone.
Free tools Windows power users keep installed
One-click scans. No signup required.
When comparing timestamps or documenting an event, state the zone alongside the formatted date. A time such as “09:00” without a zone can refer to different instants in different places, and daylight-saving changes can affect the local clock representation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What limitations should I know about?
Leap seconds
POSIX time typically excludes leap seconds rather than counting every elapsed SI second continuously. UTC is adjusted by leap seconds, so a Unix timestamp is a practical convention for software time calculations, not a literal record of every SI second across a leap-second event. The Open Group discusses the POSIX rationale for ignoring leap seconds in compatible time-difference calculations, and NIST explains UTC’s leap-second adjustments: The Open Group rationale and NIST leap-second information.
Dates before 1970
Negative values can represent instants before the epoch in GNU and POSIX implementations. For example, GNU’s @-1 is the second immediately before the epoch. Support for negative values and the dates a particular system can convert may differ across tools and platforms.
Range and precision
Do not assume every system supports the same timestamp range or precision. GNU’s documentation notes that a 32-bit signed count reaches its upper limit in January 2038; this is a limit for that representation, not a universal cutoff for all current systems. Python likewise warns that its supported range depends on the platform C library, and the precision of the system clock may be coarser than the unit used to express a value. See GNU’s epoch-seconds documentation and Python’s time documentation.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Which conversion method should I use?
- Application code: use the language’s time library, and make the input unit and output zone explicit.
- Quick shell inspection: use GNU
datewith an@-prefixed seconds value and-uwhen UTC is the intended display. - Log-processing scripts: use GNU Awk’s
mktime()andstrftime()when converting between textual fields and timestamps.
Whichever route you choose, verify the unit first, choose UTC or the intended local zone deliberately, and account for the range and precision supported by the tool running the conversion.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
