Epoch Time Converter in Linux Server
An epoch time converter on a Linux server converts Unix timestamps (seconds since January 1, 1970 UTC) into human-readable dates and vice versa, directly from the command line. This article explains the built-in commands and one-liners you can use to perform these conversions without installing extra software.
What Is Epoch Time?
Unix epoch time, also called POSIX time or Unix timestamp, is a system for tracking time as a running total of seconds. The count starts at the Unix epoch, which is January 1, 1970, at 00:00:00 UTC. Every second after that adds one to the timestamp. For example, the timestamp 1700000000 corresponds to November 14, 2023, at 22:13:20 UTC.
Linux servers store timestamps internally in this format because it is a single integer, making calculations and comparisons trivial. However, humans rarely want to read a number like 1700000000 directly, so converting it to a standard date format is a common task.
Why Convert Epoch Time on a Server?
You might encounter epoch timestamps in several places:
- Log files (e.g.,
syslog, application logs) that record events as Unix timestamps. - Database fields storing timestamps as integers.
- File timestamps shown by
statorls -l --time-style=+%s. - API responses returning time in epoch format.
- Shell scripts that need to compare or display dates.
Being able to convert these on the server itself is faster than copying them to an online converter, and it works even on isolated networks.
Using the date Command
The most straightforward tool is the date command, which is present on virtually every Linux distribution.
Convert Epoch to Human-Readable
To convert a specific epoch timestamp to a readable date, use the -d option with the @ prefix:
date -d @1700000000
Output (in your server’s local timezone):
Tue Nov 14 22:13:20 UTC 2023
If you want UTC explicitly, add the -u flag:
date -u -d @1700000000
To format the output, use the + format specifier:
date -d @1700000000 +"%Y-%m-%d %H:%M:%S %Z"
This gives 2023-11-14 22:13:20 UTC.
Convert Human-Readable to Epoch
To go the other way, use the %s format specifier with date:
date -d "2023-11-14 22:13:20 UTC" +%s
Output: 1700000000.
You can also get the current epoch time:
date +%s
Using awk for Batch Conversion
When you have a file with epoch timestamps in one column, awk can convert them all at once. For example, a file times.txt containing:
1700000000
1700003600
1700007200
You can run:
awk '{ print strftime("%Y-%m-%d %H:%M:%S", $1) }' times.txt
Output:
2023-11-14 22:13:20
2023-11-14 23:13:20
2023-11-15 00:13:20
Note that strftime uses the server’s local timezone by default. To use UTC, set the TZ environment variable:
TZ=UTC awk '{ print strftime("%Y-%m-%d %H:%M:%S", $1) }' times.txt
Using Perl for More Control
Perl is another common tool on Linux servers. To convert an epoch timestamp to a readable date:
perl -e 'print scalar(localtime(1700000000)), "\n"'
For UTC, replace localtime with gmtime:
perl -e 'print scalar(gmtime(1700000000)), "\n"'
To convert a date string to epoch:
perl -MTime::Piece -e '$t = Time::Piece->strptime("2023-11-14 22:13:20", "%Y-%m-%d %H:%M:%S"); print $t->epoch, "\n"'
This requires the Time::Piece module, which is part of the Perl core distribution.
Handling Timezones Correctly
A common mistake is forgetting that epoch time is always UTC. When you convert to a local time, the output depends on the server’s timezone setting. To avoid confusion, always specify the timezone in your output format or use the -u flag.
If you need to convert to a specific timezone, set the TZ variable:
TZ="America/New_York" date -d @1700000000
This will show the time in Eastern Time.
When converting a date string to epoch, always include the timezone offset if it is not UTC. For example:
date -d "2023-11-14 17:13:20 -0500" +%s
This correctly interprets the time as Eastern Standard Time.
Common Pitfalls and Solutions
- 32-bit overflow: Older 32-bit systems cannot handle timestamps beyond January 19, 2038. Modern 64-bit systems are fine.
- Leap seconds: Unix time ignores leap seconds, so timestamps are not exactly the number of SI seconds since the epoch.
- Negative timestamps: Dates before 1970 are represented by negative numbers.
date -d @-86400gives1969-12-31. - Format mismatches: When parsing dates, ensure the format string matches exactly. For example,
%Yis a four-digit year, while%yis two digits. - Timezone mix-ups: Always test with a known timestamp to verify your output is in the expected timezone.
Alternatives to Command Line
If you prefer a graphical interface or need to convert many timestamps quickly, you can use:
- Online converters (if the server has internet access).
- Spreadsheet software like Excel or LibreOffice Calc, which have functions for epoch conversion.
- Python one-liners:
python3 -c 'import datetime; print(datetime.datetime.fromtimestamp(1700000000))' - Scripts that wrap the
datecommand for custom formatting.
Frequently Asked Questions
How do I get the current epoch time in Linux?
Run date +%s in the terminal. It prints the current Unix timestamp in seconds.
What is the difference between epoch time and a normal date?
Epoch time is a single integer representing seconds since 1970-01-01 UTC. A normal date is a human-readable representation that includes year, month, day, and time. The same instant can be represented both ways.
Why does my converted date show the wrong timezone?
By default, date uses the server’s local timezone. Use date -u to get UTC, or set TZ to the desired timezone before running the command.
Can I convert epoch time in a script without external tools?
Yes, the date command is part of the coreutils package, which is installed by default on virtually all Linux distributions. You can also use awk or perl if they are available.
What happens if I use a timestamp larger than 2^31-1 on a 32-bit system?
On 32-bit systems, timestamps are stored as signed 32-bit integers, so they overflow after January 19, 2038. This is known as the Year 2038 problem. Most modern servers are 64-bit and avoid this issue.
How do I convert epoch time to a specific format like ISO 8601?
Use the date command with a format string: date -d @1700000000 +"%Y-%m-%dT%H:%M:%S%z". This gives 2023-11-14T22:13:20+0000 (or your local offset).
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.