Unix Timestamp Converter Guide: Epoch Time, Time Zones, and Language-Specific Examples

Overview

If you work with backend services, analytics pipelines, JWTs, database records, or event logs, you will eventually need a reliable Unix timestamp converter mindset. The goal is not only to translate a number into a readable date, but to understand what that number actually represents.

A Unix timestamp, often called epoch time, is the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC. Some systems store milliseconds instead of seconds, which is one of the biggest sources of confusion. For example:

• 1717171717 usually means seconds since the Unix epoch
• 1717171717000 usually means milliseconds since the Unix epoch

That difference matters because feeding a seconds value into a function that expects milliseconds can place your date somewhere in 1970, while doing the reverse can produce a date far in the future.

At a practical level, an epoch converter helps with four recurring tasks:

• Inspecting API responses that use numeric timestamps
• Comparing timestamps from logs across systems in different time zones
• Converting user-facing dates into machine-friendly values for storage or filtering
• Debugging expiration times in tokens, sessions, cache entries, and scheduled jobs

The safest default assumption is this: timestamps should be stored and transmitted in UTC, then formatted for a local timezone only at the display layer. That rule prevents many subtle bugs before they start.

If you frequently inspect structured payloads, pairing timestamp checks with a JSON formatter and validator can make debugging much faster, especially when nested fields contain multiple time values.

Core framework

Here is the mental model that makes timestamp work predictable. When you need to convert timestamp to date values, break the task into four decisions: unit, origin, timezone, and formatting.

1. Identify the unit: seconds, milliseconds, or something else

Before converting anything, ask what unit the source system uses.

• Seconds: common in Unix tools, many APIs, and JWT claims such as exp and iat
• Milliseconds: common in JavaScript and browser APIs such as Date.now()
• Microseconds or nanoseconds: common in some databases, analytics platforms, and lower-level languages

A quick rule of thumb: modern timestamps in seconds are usually 10 digits, while milliseconds are usually 13 digits. That is not a formal guarantee, but it is often a useful first check.

2. Confirm the reference point

In most cases, epoch time is based on the Unix epoch at 1970-01-01T00:00:00Z. But not every date field is a Unix timestamp. Some systems use ISO 8601 strings such as 2026-06-04T14:30:00Z, and others may use custom database types. Treating every number as a Unix timestamp is a shortcut that creates avoidable errors.

3. Separate UTC from local display time

The timestamp itself does not carry a human-friendly timezone label. It is just a point in time relative to UTC. Problems usually appear when one tool renders that moment in UTC and another renders it in the machine's local timezone.

For example, these may represent the same instant:

• 2026-06-04 12:00:00 UTC
• 2026-06-04 08:00:00 America/New_York

The moment is the same. Only the display changes.

When reviewing a suspicious date, ask:

• Is the stored value UTC?
• Is the application converting it to local time before display?
• Is the database client applying its own timezone setting?
• Is the log viewer rendering in browser local time?

4. Choose the output format intentionally

There is a big difference between machine-safe and human-friendly formats.

• Machine-safe: Unix timestamps, ISO 8601 UTC strings, database datetime types
• Human-friendly: Jun 4, 2026 2:30 PM, localized dates, relative times

For APIs and persistence, ISO 8601 UTC strings and numeric timestamps are usually the easiest to compare and sort. For UI output, format values close to the presentation layer so you can adapt them to the user's locale and timezone.

A repeatable debugging checklist

When a date looks wrong, run through this sequence:

1. Check whether the input is seconds or milliseconds
2. Verify whether the source value is UTC
3. Convert it to a known standard, ideally ISO 8601 UTC
4. Render it again in the expected local timezone
5. Compare the result with surrounding log entries or database records

This simple process resolves a large share of timestamp timezone issues without guesswork.

Practical examples

The examples below focus on common developer workflows rather than edge-case theory. They are designed to be easy to copy, inspect, and adapt.

JavaScript: convert Unix timestamp to date

JavaScript's built-in Date constructor expects milliseconds.

// Timestamp in seconds
const tsSeconds = 1717171717;
const dateFromSeconds = new Date(tsSeconds * 1000);
console.log(dateFromSeconds.toISOString());

// Timestamp in milliseconds
const tsMilliseconds = 1717171717000;
const dateFromMilliseconds = new Date(tsMilliseconds);
console.log(dateFromMilliseconds.toISOString());

To generate the current Unix timestamp:

// Current time in milliseconds
const nowMs = Date.now();

// Current time in seconds
const nowSeconds = Math.floor(Date.now() / 1000);

To format for a specific timezone:

const date = new Date(1717171717000);
const formatted = new Intl.DateTimeFormat('en-US', {
  timeZone: 'America/New_York',
  dateStyle: 'medium',
  timeStyle: 'long'
}).format(date);

console.log(formatted);

This is often safer than relying on the environment default, especially in server-rendered applications.

TypeScript: create a small epoch converter utility

export function epochToIso(input: number): string {
  const isSeconds = input < 1000000000000;
  const ms = isSeconds ? input * 1000 : input;
  return new Date(ms).toISOString();
}

export function isoToEpochSeconds(iso: string): number {
  return Math.floor(new Date(iso).getTime() / 1000);
}

This kind of wrapper is useful in shared frontend and backend codebases because it makes the unit conversion explicit.

Python: convert timestamp to UTC and local time

from datetime import datetime, timezone

# Timestamp in seconds
ts = 1717171717

utc_dt = datetime.fromtimestamp(ts, tz=timezone.utc)
print(utc_dt.isoformat())

# Convert ISO string back to epoch seconds
iso_value = '2026-06-04T14:30:00+00:00'
parsed = datetime.fromisoformat(iso_value)
print(int(parsed.timestamp()))

If you need local timezone behavior, be careful not to mix naive and timezone-aware datetime objects. In most backend code, using timezone-aware values consistently is the better long-term choice.

SQL: reading and writing timestamps

SQL syntax varies by database, but the pattern is similar: know the storage type, know the timezone rules, and convert close to the query only when necessary.

Example patterns you may see:

-- Pseudocode-style examples; exact syntax differs by database

-- Convert epoch seconds to timestamp
SELECT to_timestamp(1717171717);

-- Convert a timestamp to epoch seconds
SELECT extract(epoch FROM some_timestamp_column);

The important part is not memorizing one vendor's function names. It is verifying these details before you trust the result:

• Does the column store timezone-aware values?
• Is the database session timezone set explicitly?
• Is your query tool displaying values in UTC or local time?

If you are already cleaning up database output, it can help to pair time debugging with a readable query workflow using an SQL formatter.

Command line: fast checks during debugging

Quick command-line conversions are useful when investigating logs or deployment issues.

# GNU date style example: epoch to UTC
# date -u -d @1717171717

# Current epoch seconds
# date +%s

Exact flags differ between environments, especially between GNU and BSD tools, so it is worth checking your platform's manual page before turning one-liners into scripts.

API example: expiration timestamps

Many APIs and tokens use epoch seconds for expiration windows. JWTs are a classic example. If a token appears to expire too early or too late, compare the current epoch time with the token's exp value and confirm whether both are measured in seconds. For a deeper walkthrough of token fields and expiration checks, see the JWT decoder guide.

Build a small in-house converter page

If your team repeatedly troubleshoots time values, a simple internal utility can save effort. A practical page might include:

• An input field that auto-detects seconds vs milliseconds
• UTC output as ISO 8601
• Local timezone output
• A dropdown for named time zones
• Reverse conversion from date string to epoch
• A short warning when the input is ambiguous

This kind of tiny tool fits well beside other developer productivity utilities such as a URL encoder/decoder, Base64 tool, or regex tester.

Common mistakes

Most timestamp bugs come from a short list of recurring errors. If you recognize these patterns early, debugging becomes much faster.

Confusing seconds and milliseconds

This is the most common error in any epoch converter workflow. JavaScript is a frequent source because Date.now() returns milliseconds, while many APIs return seconds.

Symptom: the converted date lands in 1970 or in a distant future year.

Fix: inspect the digit length and confirm the source documentation or payload convention.

Assuming the timestamp includes a timezone label

A Unix timestamp represents an instant relative to UTC. It does not contain a display timezone on its own.

Symptom: two tools show different times for the same value.

Fix: compare the values in ISO UTC first, then render for the required timezone.

Mixing naive and timezone-aware datetime values

This problem is especially common in Python and database code.

Symptom: comparisons fail, conversions shift unexpectedly, or DST boundaries behave strangely.

Fix: standardize on timezone-aware UTC values in storage and backend logic.

Parsing user input without defining the timezone

A date like 2026-06-04 09:00 is incomplete unless you know the timezone context.

Symptom: scheduled events fire at the wrong local hour.

Fix: require either a timezone-aware input or a clearly defined application default.

Trusting the local machine timezone during debugging

Logs from containers, CI jobs, developer laptops, and production servers may all render differently.

Symptom: the same event appears to happen at inconsistent times across environments.

Fix: normalize comparisons in UTC first. Local formatting should come second.

Ignoring daylight saving transitions

Daylight saving time does not change UTC timestamps, but it does affect local display times and user expectations.

Symptom: recurring events shift by an hour during part of the year.

Fix: store the absolute instant separately from any recurrence rules and named timezone context.

Using loose string formats for API contracts

Human-readable dates can be ambiguous across locales.

Symptom: one system interprets 06/04/2026 as June 4, another as April 6.

Fix: prefer ISO 8601 or explicit epoch values in machine-to-machine communication.

When to revisit

Timestamp handling feels stable until a system boundary changes. This is the right topic to revisit whenever your inputs, environments, or tooling evolve.

Review your approach when any of these happen:

• You integrate a new API and its time fields are undocumented or inconsistent
• You move logic from browser code to server code, or vice versa
• You switch databases, ORM layers, or query clients
• You add scheduling, recurring events, or user-selected time zones
• You start storing dates in tokens, cache keys, or event streams
• You discover production bugs around daylight saving changes or expiration windows

A practical maintenance routine is simple:

1. Document whether each field uses seconds, milliseconds, or ISO strings
2. Store canonical values in UTC
3. Add test cases around timezone boundaries and DST changes
4. Expose formatting close to the UI, not deep in core business logic
5. Create one shared utility per language instead of repeating ad hoc conversions

If you maintain reusable scripts or internal tools, this is also a good place to add lightweight validation. For example, reject ambiguous input lengths, warn when a timestamp appears out of range, and include unit tests for known examples. Teams that publish or reuse shared helpers should consider a basic testing workflow similar to the practices outlined in testing and validating script libraries.

As a final rule of thumb, when a date looks wrong, do not start by blaming the timezone library. Start by checking the unit, then the UTC assumption, then the display layer. That order solves more problems than most complex fixes.

Used well, a Unix timestamp converter is more than a convenience tool. It is a debugging shortcut, a contract check between systems, and a reliable way to keep time data consistent across languages and environments. Save this guide as a reference for the next time an API returns a mysterious 10-digit number or a dashboard shows a date that does not line up with your logs.