date Command - Formatting and Calculating Dates

date Command - Formatting and Calculating Dates
Reading time: About 10 min Difficulty: Beginner

What you'll be able to do

  • Shape dates and times any way you want with `date +FORMAT`
  • Calculate dates such as yesterday or N days later with `date -d`
  • Convert between epoch seconds and dates with `date +%s` and `date -d @seconds`

Prerequisites (read these first)

What Is the date Command?

Lina: Linny-senpai, I want to put today's date in my backup file names. Do I really have to type it by hand every time?
Linny-senpai: That's exactly what the date command is for. Type it and it prints the current time.
Linny-senpai: Write date +%Y%m%d and it formats that as 20260605. You can drop the result straight into a file name.
Lina: So one command can build a date string for me.
Linny-senpai: Yep. It can also calculate "3 days ago" or "next friday". Switching time zones works the same way.

The date command shows the current date and time. It can also shape that output however you like.

You will use it for log timestamps, backup file names, and date math inside scripts. It comes up almost every day.

Words used here (sorted out first)

  • Format: how the date should be printed. "Layout" and "shape" mean the same thing here.
  • Format specifier: a symbol starting with %, such as %Y. Each one stands for a single piece of the date.
  • Locale: your language and region settings. Weekday names and similar text change with it.
  • Time zone: the time offset of a region. Japan uses JST, and the world reference is UTC.
  • Epoch seconds: the number of seconds since 1 January 1970. "Unix time" means the same thing.

Environment

  • OS: Ubuntu / typical Linux
  • GNU coreutils date (the BSD version on macOS uses a different syntax — see section 7)
  • The output in this article is shown in Japan time (JST). Times shift on machines set to another time zone

In one line

date +FORMAT builds a date string in any shape you want.

Example: date +%Y-%m-%d → 2026-06-05

What You'll Learn

  • Show the current time with date, and shape it with date +%F and friends
  • Combine format specifiers like %Y, %m, and %d into any layout
  • Calculate dates such as yesterday, N days later, or next week with date -d
  • Get epoch seconds with date +%s, and convert back with date -d @seconds
  • Switch time zones with TZ='UTC' date or date -u
  • Watch out for the differences between Linux (GNU date) and macOS (BSD date)

1. Show the Current Time

Conclusion: Run date with no arguments for the current time; use date +FORMAT to change how it looks.

With no options at all, date prints the current date and time.

$ date
Fri Jun  5 15:52:59 JST 2026

The exact text depends on your system's locale and time zone settings. The weekday and the JST part are the parts that change.

When you want just the date, or just the time, use the format specifiers in the next section.

2. Format the Output (%Y %m %d…)

Conclusion: Put specifiers like %Y (year), %m (month), %d (day) after date + to shape the output.

Write format specifiers after the +. You then get exactly that shape.

$ date +%Y-%m-%d
2026-06-05
$ date "+%Y/%m/%d %H:%M:%S"
2026/06/05 15:52:59

If your format contains a space, wrap the whole thing in "..." (double quotes).

Without quotes the shellAn interactive program that reads the commands you type and runs them. splits the format at the space. date then treats the second half as an extra argument and stops with an error.

$ date +%Y-%m-%d %H:%M:%S
date: extra operand '%H:%M:%S'
Try 'date --help' for more information.

2-1. Common Format Specifiers

Specifier Meaning Example
%Y 4-digit year 2026
%m Month (01–12) 06
%d Day (01–31) 05
%H Hour (00–23) 15
%M Minute (00–59) 52
%S Second (00–60) 59
%A Weekday (full) Friday
%a Weekday (short) Fri
%j Day of the year 156
%s Epoch seconds 1780642379
Lina: That's a lot of specifiers. I'll never remember them all.
Linny-senpai: You don't have to. The most common combinations have shortcuts.

2-2. Handy Shortcuts

$ date +%F
2026-06-05
$ date +%T
15:52:59
  • %F equals %Y-%m-%d (the ISO 8601 date)
  • %T equals %H:%M:%S (the time)

When in doubt, remember %F for the date and %T for the time. Those two cover most situations.

2-3. Lina Gets Stuck: Mixing Up %m and %M

Lina: Senpai, I asked for a year-month-day and the month came out as 52. There is no such month.
$ date +%Y-%M-%d
2026-52-05
Lina: Did I break the date somehow?
Linny-senpai: Nothing is broken. Look closely: you wrote an uppercase %M.
Linny-senpai: Lowercase %m is the month, and uppercase %M is the minute. It is 15:52 right now, so 52 landed in the month slot.
Lina: Wait, upper and lower case mean different things? That caught me off guard.
Linny-senpai: They do. Dates use lowercase and times use uppercase. %Y for the year is the one exception.
Lina: It printed a number, so I didn't notice. No error makes it scarier.
Linny-senpai: Exactly. So whenever you change a format, print it once and look at the result. That is the surest way to catch it.

%m (month) and %M (minute) are easy to swap, and so are %d (day) and %D (month/day/year). A mistake does not raise an error. It prints a plausible-looking number instead, which is why checking the output matters.

3. Templates for File Names and Logs

Conclusion: Embed $(date +%Y%m%d) in a file name to create dated files automatically.

$(...) inserts a command's output into a string. This is called command substitution, and it is the classic trick for backups.

$ cp data.db "backup-$(date +%Y%m%d).db"

This creates a file named backup-20260605.db.

$ echo "[$(date '+%Y-%m-%d %H:%M:%S')] Process started" >> app.log

Use this when you want to add your own timestamp to a log. Example output:

[2026-06-05 15:52:59] Process started

Avoid putting %T directly in file names. %T contains a colon (:), and some environments and file systems handle that poorly.

To put a time in a name, use %H%M%S with no separators instead.

4. Calculate Dates (yesterday, 3 days later, N days ago)

Conclusion: Use date -d "string" to calculate dates like yesterday, 3 days ago, or next friday in plain English.

Pass the date you want to the -d (or --date) option, written in plain English.

$ date -d "yesterday" +%F
2026-06-04
$ date -d "3 days ago" +%F
2026-06-02
$ date -d "next friday" +%F
2026-06-12

You can also calculate from a base date that you choose yourself.

$ date -d "2025-01-01 +30 days" +%F
2025-01-31
Lina: Whenever I count 30 days ahead by hand, I get it wrong where the month rolls over.
Linny-senpai: Right, and date does that part correctly. It knows how long each month is, and it handles leap years.
Linny-senpai: That makes it far safer than counting in your head.

Common expressions

  • tomorrow / yesterday
  • 3 days ago / 2 weeks / 1 month
  • next monday / last sunday

This relative date math is a GNU date (Linux) feature. macOS uses a different syntax, so these will not work there. See Section 7 for details.

5. Epoch Seconds (Unix Time)

Conclusion: date +%s prints seconds since 1970, and date -d @seconds converts them back to a date.

Epoch seconds (Unix time) is the number of seconds since 1970-01-01 00:00:00 UTC.

Programs and logs often store time in this form. It does not depend on region or formatting, which makes it easy to compare.

$ date +%s
1780642379

To convert epoch seconds back into a readable date, prefix the number with @.

$ date -u -d @1700000000 "+%Y-%m-%d %H:%M:%S %Z"
2023-11-14 22:13:20 UTC

-u is what pins this output to UTC. Without it, the result follows your machine's time zone.

In Japan time (JST, UTC+9) the same command prints 2023-11-15 07:13:20, which is the next day. Machines set to a different zone show a different date, so add -u or TZ when you need a fixed answer.

A log sometimes records only a number like 1700000000, which you cannot read as it stands. date -d @that-number converts it to a date right away.

6. Switch Time Zones (TZ / -u)

Conclusion: date -u shows UTC, and TZ='Area/City' date shows the time in any time zone.

Add -u to display the time in UTC (Coordinated Universal Time).

$ date -u "+%Y-%m-%d %H:%M %Z"
2026-06-05 06:52 UTC

To see the time in a specific region, set the TZ environment variableA named value that the shell or a program can look up while running. right before the command.

$ TZ='America/New_York' date "+%Y-%m-%d %H:%M %Z"
2026-06-05 02:52 EDT
$ TZ='Asia/Tokyo' date "+%Y-%m-%d %H:%M %Z"
2026-06-05 15:52 JST
Lina: So writing TZ=... before the command changes the time zone just for that one run?
Linny-senpai: Exactly. TZ='Area/City' date only applies while that one date runs.
Linny-senpai: Your system-wide setting stays untouched, so it is safe to experiment.
Lina: That's handy for checking the time on an overseas server.

You can list the valid zone names with timedatectl list-timezones. Asia/Tokyo, America/New_York, and Europe/London are examples.

TZ is an environment variable, so reading Working with Environment Variables will deepen your understanding.

7. Mind the Difference with macOS (BSD date)

Conclusion: Linux ships GNU date; macOS ships BSD date, whose date math and epoch syntax differ.

The commands in this article assume Linux such as Ubuntu (GNU coreutils date).

The date that ships with macOS is the BSD version, so some of its options differ.

What you want Linux (GNU) macOS (BSD)
3 days ago date -d "3 days ago" date -v-3d
Epoch → date date -d @1700000000 date -r 1700000000
Parse a date string date -d "2025-01-01" date -j -f "%Y-%m-%d" "2025-01-01"

A date -d ... command you found online may complain with something like illegal option on macOS. In that case you are most likely on the BSD version.

Run date --version. If it prints GNU coreutils, you are on the GNU version.

8. Mini Exercises: Try It Yourself

Conclusion: Three drills — building a format, calculating a date, and converting epoch seconds — confirm the basics of date by hand.

Lina: I've got the knowledge. I want to confirm it hands-on.
Linny-senpai: Good. Here are three tasks. Try them in your terminal.

Task 1: Print today's date in the form 2026/06/05, using slashes.

Show hint 1 (direction)

After the +, line up the symbols for year, month, and day, joined by slashes. There are no spaces involved.

Show hint 2 (command name)

The command is date. The symbols for year, month, and day are in the table in section 2. Note that the month is lowercase.

Show answer 
$ date +%Y/%m/%d
2026/06/05

Task 2: Print the date 3 days from now in YYYY/MM/DD form.

Show hint 1 (direction)

Two things at once. You need the option that calculates a date, plus the format that shapes it.

Show hint 2 (command name)

The command is date. The option that calculates a date is in section 4, and the format syntax is in section 2.

Show answer 
$ date -d "3 days" "+%Y/%m/%d"
2026/06/08

"3 days" means "3 days from now". Writing "+3 days" gives the same result.

Task 3: Convert the epoch seconds 1700000000 back into a date in YYYY-MM-DD form, in UTC.

Show hint 1 (direction)

A bare number is not read as a date. Put a marker in front of it to say that it is epoch seconds. Add the option that switches the output to UTC.

Show hint 2 (command name)

The command is date. The marker for epoch seconds is in section 5, and the option that switches to UTC is in section 6.

Show answer 
$ date -u -d @1700000000 +%F
2023-11-14

%F means the same as %Y-%m-%d. Without -u the answer follows your local time zone, so it can land on the next day.

9. Review

Lina: Let me sum up. date +FORMAT decides the shape, and date -d calculates the date.
Linny-senpai: Exactly. You can use both at once, so a calculated date can come out in any shape you like.
Lina: In a format, %m is the month and %M is the minute. I'll always check that one on screen.
Linny-senpai: Perfect. And don't forget the @ when converting epoch seconds back.

Today's 3-Line Summary

  1. date +%F gives the date and date +%T gives the time. When in doubt, use those two
  2. %m is the month and %M is the minute. A mix-up raises no error, so check the output
  3. date -d "3 days ago" calculates dates, and date -d @seconds turns epoch seconds back into a date

Summary

Task Command
Show the current time date
Show the date only date +%F (= date +%Y-%m-%d)
Show the time only date +%T
Date for a file name date +%Y%m%d
Calculate a date date -d "3 days ago" +%F
Get epoch seconds date +%s
Convert epoch to a date date -d @1700000000
Show UTC date -u
Use a specific time zone TZ='Asia/Tokyo' date

Three things to try right now

  1. Run date +%F to show today's date
  2. Run date -d "tomorrow" +%F to calculate tomorrow
  3. Run cp something.txt "backup-$(date +%Y%m%d).txt" to make a dated file

Next Reading

Share this article

Next steps

Next article → Setting Up Aliases - How to Shorten Linux Commands Practice with quiz → Verify your understanding Practice with lesson → Run commands in the terminal