iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A Unix timestamp is a number that identifies an instant by counting from 1970-01-01 00:00:00 UTC. Before converting one, check its unit: seconds and milliseconds use different scales. Then choose whether to display the instant in UTC or local time.
What is a Unix timestamp?
A Unix timestamp represents an instant as a count relative to an agreed starting point, called the epoch. In conventional Unix and POSIX usage, that count is in seconds. Some interfaces can include fractional seconds, while other systems use a smaller unit such as milliseconds.
The Python time-module documentation defines the epoch as the point returned by time.gmtime(0): January 1, 1970, 00:00:00 UTC on all platforms. GNU’s examples make the count concrete: @0 is the epoch, and @1 is one second later.
A timestamp is not a formatted date or a time-zone label. It identifies an instant; a conversion turns that instant into calendar fields for a chosen zone. For a consistent reference in logs and APIs, UTC is usually the clearest display. A local-time display depends on the machine’s time-zone and daylight-saving rules.
Is a Unix timestamp in seconds or milliseconds?
It depends on the source. Standard POSIX examples and Python’s time.time() use seconds; Python returns a float, so the value can include a fractional part. The web-platform convention described by MDN is milliseconds. Treat the unit as part of the API or file’s data contract rather than guessing from the digits alone.
For a seconds-based conversion function, divide milliseconds by 1,000 first. For example, 1700000000000 milliseconds becomes 1700000000 seconds. Feeding the millisecond value directly to a seconds-based function can produce a date far outside the intended range.
How do I convert a Unix timestamp to a date?
Convert in Python
Use time.gmtime() to get UTC calendar fields or time.localtime() to use the machine’s local time zone:
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, floatIf the input is in milliseconds, convert the unit before calling the seconds-based function:
Rank #2
- The Unix Programming Environment (Prentice-Hall Software Series)
- Product Type: ABIS_BOOK
- Pearson
milliseconds = 1_700_000_000_000
seconds = milliseconds / 1000
print(time.gmtime(seconds))These functions return structured time fields, not necessarily a ready-to-display string. Format the result as needed by your application, and label UTC explicitly when that is the intended zone.
Convert with GNU date
On systems with GNU date, pass epoch seconds with an @ prefix. Use -u to request UTC output:
date -u -d '@1700000000'GNU documents @0 as 1970-01-01 00:00:00 UTC, @1 as one second later, and @-1 as the preceding second. The command shown is for GNU date; other implementations of date may use different options or syntax.
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 errorsUse GNU Awk in a script
GNU Awk’s mktime() converts textual date and time fields into a timestamp, while strftime() formats a timestamp. These functions are useful when a script needs to parse, compare, or reformat times in log data. See the GNU Awk time-functions documentation for their syntax and details.
Rank #3
- Used Book in Good Condition
How do I convert epoch time to UTC?
Choose an explicitly UTC conversion rather than relying on the machine’s default zone. In Python, use time.gmtime(timestamp); with GNU date, use date -u -d '@timestamp', replacing timestamp with the numeric seconds value. If the source uses milliseconds, divide by 1,000 before conversion.
In Python, time.localtime() instead returns fields in the machine’s local time zone. The underlying instant is unchanged; only the calendar representation differs. This matters around daylight-saving transitions, when local clock readings may be ambiguous or skipped.
What can go wrong with Unix timestamps?
Interpreting the wrong unit
Seconds versus milliseconds is one of the most consequential mistakes. Check the API documentation or data format, and normalize values to a known unit before arithmetic or conversion. Fractional seconds also need care: an API may preserve them, while another conversion or display step may round or discard precision.
Free tools Windows power users keep installed
One-click scans. No signup required.
Assuming timestamps count every SI second
Conventional POSIX time typically excludes leap seconds. UTC is adjusted by leap seconds, so Unix time is a practical software convention, not a literal continuous count of every SI second across a leap-second event. The Open Group explains that ignoring leap seconds supports compatible time-difference calculations; NIST describes UTC’s leap-second adjustments. See the Open Group rationale and NIST leap-second information.
Rank #4
Converting dates before 1970
Negative values can represent instants before the epoch in GNU and POSIX implementations, as GNU’s @-1 example illustrates. Support for negative timestamps and their full range is not identical across every tool, platform, or library, so verify the behavior of the environment that will run your code.
Assuming every platform has the same range or precision
Supported dates and precision depend on the system and library. Python notes that its conversion range can be limited by the underlying platform C library, and out-of-range inputs may raise errors. Clock precision can also be less than the apparent units of a returned value suggest.
GNU’s documentation notes that a 32-bit signed count reaches its upper limit in January 2038. That is a limitation of such 32-bit representations, not a universal cutoff for all systems. Check the documentation for the target platform when dates near a supported-range boundary matter. Python’s time module documentation and GNU’s seconds-since-the-epoch documentation describe these platform and range considerations.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Which 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: GNU
dateaccepts@-prefixed epoch seconds and can print UTC with-u. - Log-processing scripts: GNU Awk provides
mktime()andstrftime()for parsing and formatting time values.
For Python’s documented functions and behavior, consult the Python 3.14.8 time documentation. The separate Python 3.12.15 documentation also describes the seconds-based conversion used for millisecond inputs after dividing by 1,000. MDN summarizes the web-platform convention in its Unix time glossary.
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.
