Home / Alt manpages / date(1)

  • date(1)
  • User command
  • linux

Use GNU date for Timestamps, Time Zones and Safe Checks

GNU date can print a sortable timestamp, convert Unix seconds and decode "next Thursday" without ever touching the host clock. You will try each of those, plus another time zone, in about 10 minutes. You need a shell, GNU coreutils and an ordinary user account. The installed command here is GNU coreutils 9.4, and other releases can differ in small parsing or formatting details.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm the command and its version

Check which executable your shell will run. This saves you debugging the wrong implementation, especially on systems where a BSD date is also around.

$ command -v date
/usr/bin/date
$ date --version | head -2
date (GNU coreutils) 9.4
Copyright (C) 2023 Free Software Foundation, Inc.

Checkpoint

The command should identify itself as GNU coreutils. If it does not, read that implementation's manual page before copying these options.

2. Print a timestamp that scripts can sort

With no date source selected, date prints the current local time. A format string beginning with + controls the output.

Use ISO 8601 when another program or person needs to read the date without guessing whether a number is a month or a day.

$ date --iso-8601=seconds
2026-09-22T23:28:53+01:00
$ date -u --iso-8601=seconds
2026-09-22T22:28:53+00:00

Your values will differ. The local form includes the host's UTC offset; -u asks for Coordinated Universal Time. For a compact format used in filenames, use explicit format directives:

$ date -u '+%Y%m%dT%H%M%SZ'
20260922T222853Z
  • %Y is the year, %m the month and %d the day.
  • %H is the hour, %M the minute and %S the second.
  • The final Z is literal text, correct here because UTC was selected with -u.

Tip

Quote the whole format so the shell does not interpret punctuation or spaces.

3. Format a known date without touching the clock

--date=STRING asks GNU date to describe a supplied time rather than now. The parser accepts ISO-like dates, relative phrases and Unix seconds. That is handy for reports and checks, but free-form input deserves a visible verification step.

$ date --date='@0' --utc '+%Y-%m-%d %H:%M:%S %Z'
1970-01-01 00:00:00 UTC
$ date --date='2026-09-24 09:00' --iso-8601=minutes
2026-09-24T09:00+01:00
$ date --date='next Thursday' --iso-8601=minutes
2026-09-24T00:00+01:00

The @ form reads a number as seconds since the Unix Epoch, which is 1970-01-01 00:00 UTC.

Relative words are evaluated from the machine's current time and local time zone, so their result changes as time passes.

Warning

Do not put an untrusted string directly into a command. Validate the input and quote it before passing it to a shell command.

For a batch of independent dates, put one date string per line in a file and use --file:

$ printf '%s\n' '2026-09-22 12:00 UTC' '2026-09-24 09:00' > /tmp/date-input.txt
$ date --file=/tmp/date-input.txt --iso-8601=seconds
2026-09-22T12:00:00+00:00
2026-09-24T09:00:00+01:00

The temporary file is input only. Remove it when you have finished with rm -- /tmp/date-input.txt; that deletion is not reversible through date.

4. Inspect another time zone

The TZ environment variable changes how date displays a time without changing the host's configured zone. That is safer than editing system configuration when you only need to answer a scheduling question.

$ TZ='America/Los_Angeles' date '+%Y-%m-%d %H:%M %Z'
2026-09-22 15:28 PDT
$ TZ='Asia/Tokyo' date '+%Y-%m-%d %H:%M %Z'
2026-09-23 07:28 JST
  • The zone must exist. The named zone has to be in the system time-zone database.
  • Abbreviations are output only. PDT is something date prints, not a reliable input identifier.
  • Use full names. Prefer Europe/London or America/Los_Angeles, because they carry daylight-saving rules.

5. Read a file's modification time

Use --reference=FILE when you want the timestamp of an existing file rather than the current time. It does not edit the file.

$ touch /tmp/date-check.txt
$ date --reference=/tmp/date-check.txt --iso-8601=seconds
2026-09-22T23:28:53+01:00
$ stat --format='mtime: %y' /tmp/date-check.txt
mtime: 2026-09-22 23:28:53.000000000 +0100

The displayed precision and wording differ between the two commands, but both refer to the file's modification time. The temporary file in this example can be removed after inspection.

Warning

If you need to preserve a file's timestamp, do not use touch on it. That changes the timestamp.

6. Treat system-clock changes as maintenance

Warning

--set=STRING, or the older positional setting form, changes the host system time. This normally needs elevated privileges and can disrupt logs, scheduled jobs, authentication, databases and other services. Stop before running it on a production host.

For a real correction, prefer the system's time-synchronisation service, and coordinate a maintenance window.

If you have a documented reason and a rollback value, record the current clock first, then ask an administrator to set the replacement:

$ date --iso-8601=seconds
2026-09-22T23:28:53+01:00
$ sudo date --set='2026-09-22 23:30:00'
Tue Sep 22 23:30:00 BST 2026
$ date --iso-8601=seconds
2026-09-22T23:30:00+01:00

The output is illustrative, so substitute an approved value, not the example.

Recovery

There is no automatic undo. Use the recorded previous value with the same sudo date --set='...' operation, then restore normal time synchronisation according to your host's administration policy. Do not use sudo for the read-only examples above.

7. Diagnose parsing and formatting mistakes

When an input is ambiguous, add --debug. GNU date annotates its interpretation and warns about questionable usage on standard error.

$ date --debug --date='2026-09-24 09:00' --iso-8601=minutes
2026-09-24T09:00+01:00

Keep the diagnostic lines your installed version prints, since their wording is version-specific. If the command rejects a string, replace it with an explicit ISO-like date and time zone, then verify the result.

Remember that --date, --file, --reference and --resolution are mutually exclusive. --resolution reports the available timestamp resolution, not the current time:

$ date --resolution
0.000000001

Done means

  • Implementation confirmed. You checked that the shell is using GNU coreutils 9.4, or read the manual for the implementation you have.
  • Timestamps on demand. You can produce local, UTC and explicitly formatted timestamps.
  • Safe conversions. You can convert an Epoch value and test a date string without changing the clock.
  • Other zones. You can inspect another time zone with a temporary TZ setting.
  • Clock changes respected. You know that changing the system clock needs a maintenance decision, elevated access and a recorded rollback value.