How To Format Date and Time in Linux, macOS, and Bash?

  • HOME
  • >
  • LINUX
  • >
  • How To Format Date and Time in Linux, macOS, and Bash?
Last Updated: 
subscribe to my newsletter

Performing date and time operations in a shell script is a fairly common task when automating backup processes or generating scheduled reports. Unfortunately, dealing with date and time operations in shell or trying to format a date is never straightforward as the Linux date and macOS date command line behavior might differ slightly.

This post provides examples on how to do date operations and format dates on Linux and macOS with the date and awk command lines and with the printf bash shell command builtin.

👉 All the Linux options presented in this post are fully compatible with all Linux distributions deployed on Windows 10 with WSL. Read more about Linux on Windows with my post Running Bash Script With Ubuntu On Windows 10 Using WSL.

Introduction to Date and Time

The complexity of dealing with date and time goes beyond the tooling or programming problem. Very often, consideration will need to be taken regarding timezone, daylight saving, leap year, leap second, standard format, and even sometimes the type of calendar.

What are the different calendar types?

Calendars are a way to organize days for various purposes by giving names to given periods like days, weeks, months, and years. A date is the representation of a single day in a calendar. There is a lot of calendar systems in use still to date some are based on the motion of the moon (Lunar calendars) or perceived seasons (Solar calendars).

The Gregorian calendar is the most widely used calendar system today and is often considered the international standard for civil use. It is a solar calendar with 12 months of 28 to 31 days each and based on 365 days a year, except for leap years, which add an extra day (a leap day) every 4 years in February.

The following post assumes the use of the Gregorian calendar unless specified otherwise.

What are UTC and Timezone?

Universal Coordinated Time (UTC), also known as Coordinated Universal Time, is the co-ordination of time and frequency around the world which began on January 1st, 1960. It is the basis of current timekeeping and is the baseline of all local times. The timezone offset for UTC is 0 and would be indicated with the letter Z. UTC is often interchanged with the Greenwich Mean Time (GMT) though this is not correct as GMT is a timezone, used in some European and African countries, while UTC is a time standard, therefore UTC is never used as a local time.

With UTC come the time zones which are regions of the globes that observe a standard time for the day to day purposes. A time zone relates to local time and is offset from UTC. The time zone offset to UTC is not always represented by whole hours, for example, the Indian Standard Time (IST) is UTC+5:30. Timezones may be identified with a time zone identifier like America/Los_Angeles in the IANA Time Zone Database (also called tzdata, tz, or zoneinfo). Note that the time zone database from IANA contains critical historical information which is necessary when dealing with the local date and time representation at a given time.

Some local time may switch part of the year to a time zone that includes a notion of daylight saving time (DST).

What is Unix Time?

The Unix time is a point in time that describes the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), excluding leap seconds. It is part of the POSIX specification. Other frequent names for Unix time are Epoch time, POSIX time, seconds since the Epoch, or UNIX Epoch time. Every day in Unix time assumes an 86,400 seconds day. It is not a true representation of UTC.

👉 Read more about leap seconds and go back in time with our post on the 2012 leap second bug that took down half of the internet: Getting Ready For The Leap Second.

Unix time starts at zero (0) which is 00:00:00 UTC on 1 January 1970.

⚠️ Some systems still store this value in as a signed 32-bit integer which may cause large bugs on January 19, 2038 once the upper limit of the integer is reached. This is known as the Y2038 bug (Year 2038).

What is the ISO 8601 standard?

The ISO 8601 is the International Standard for the representation of dates and times to ensure consistent representation across systems in a gregorian calendar. It is a field-based format where dates and times are identified (2020-05-09T03:44:25Z) in contrast to the Unix Time (1547092066).

The standard uses the specifiers from the below table to represent a date and time. Note that the standard calls for a minimum of 4 digits year to avoid a repeat of the Y2K bug (Year 2000).

specifier/token meaning
YYYY four-digit year
MM two-digit month (01=January, etc.)
ww week number from 1 to 53
D week day number from 1 to 7 and beginning with Monday
DD two-digit day of month (01 through 31)
hh two digits of hour (00 through 23) (am/pm NOT allowed)
mm two digits of minute (00 through 59)
ss two digits of second (00 through 59)
s one or more digits representing a decimal fraction of a second
Z or +hh:mm or -hh:mm time zone designator
/ used to express a time interval between two time points

Examples:

  • 2020-05-09T13:49:54+00:00
  • 2020-05-09T13:49:54Z

Using Calendars from the shell command line

Julian and Gregorian calendars with cal and ncal

The command line tools cal and ncal on linux and macOS provide a convenient way to display Julian or Gregorian calendar information from a shell. The main difference between the two is with the default calendar view as cal will show each day of the week as a column while the ncal command will show, by default, the day of the week on different rows (vertical format or 'sideways'). That said, ncal with the option -C can also display the day of the week in column as cal does, and cal itself with the -N option can show the vertical view.

The cal utility displays a simple calendar in a traditional format and ncal offers an alternative layout, more options, and the date of Easter.

Both utility will highlight the current date.

[me@linux ~]$ cal
      May 2020        
Su Mo Tu We Th Fr Sa  
                1  2  
 3  4  5  6  7  8  9  
10 11 12 13 14 15 16  
17 18 19 20 21 22 23  
24 25 26 27 28 29 30  
31         

[me@linux ~]$ ncal
    May 2020          
Mo     4 11 18 25   
Tu     5 12 19 26   
We     6 13 20 27   
Th     7 14 21 28   
Fr  1  8 15 22 29   
Sa  2  9 16 23 30   
Su  3 10 17 24 31   

[me@linux ~]$ cal 2020
                            2020
      January               February               March          
Su Mo Tu We Th Fr Sa  Su Mo Tu We Th Fr Sa  Su Mo Tu We Th Fr Sa  
          1  2  3  4                     1   1  2  3  4  5  6  7  
 5  6  7  8  9 10 11   2  3  4  5  6  7  8   8  9 10 11 12 13 14  
12 13 14 15 16 17 18   9 10 11 12 13 14 15  15 16 17 18 19 20 21  
19 20 21 22 23 24 25  16 17 18 19 20 21 22  22 23 24 25 26 27 28  
26 27 28 29 30 31     23 24 25 26 27 28 29  29 30 31              
...     

To get the calendar view of a specific year and month with cal (or ncal) you can use the -d option followed by the year and month.

[me@linux ~]$ cal -d 1991-11
   November 1991      
Su Mo Tu We Th Fr Sa  
                1  2  
 3  4  5  6  7  8  9  
10 11 12 13 14 15 16  
17 18 19 20 21 22 23  
24 25 26 27 28 29 30  

To display the calendar using Julian days (numbered days from January 1 to December 31) with cal and ncal you can use the -j option, for example, you can see below that 2020 has 366 days and is a leap year and the last day of the year will be a Thursday.

[me@linux ~]$ cal -j -m 12
       December 2020         
 Su  Mo  Tu  We  Th  Fr  Sa  
        336 337 338 339 340  
341 342 343 344 345 346 347  
348 349 350 351 352 353 354  
355 356 357 358 359 360 361  
362 363 364 365 366          

Now, to be honest, besides getting a quick calendar view from the command line, I have never found those two utilities being used reasonably in any automation or production systems. This is more for fun or to be informative than anything else.

Holidays and Events with the calendar command line on Linux

The Linux calendar command line is defined as a reminder service that can send notifications and check a given directory for specified calendars definition to displays lines that will begin with a given date. This can be convenient to list a country's frequent holidays or create your customized list of recurring events. The tool is available on Linux and will require the cpp binary to compile the calendar files.

[me@linux ~]$ calendar -f /usr/share/calendar/calendar.usholiday -l 30 -B 30
Apr 15  Income Tax Day, USA.
Apr 28* Arbor Day, USA (varies from state to state)
May 10* Mother's Day (2nd Sunday of May)
May 16* Armed Forces in USA Day (3rd Saturday of May)
May 25* Memorial Day in USA (Last Monday of May)

Display and Format dates with the shell date command line

The most widely used shell command line utility to manipulate a date in Linux and Unix/macOS is certainly to use the shell date command. Remember that macOS is based on Unix and will come with the Unix version of the date shell command. Though, there is some important catch to be aware as the implementation between Linux and Unix diverges greatly.

The date shell command uses the date [options] +FORMAT where the format is a serie of format specifiers used to define the output format of the date and time. The options and format specifiers may vary between platforms. The date format example below will work across Unix/macOS and Linux platforms.

[me@linux ~]$ date '+Today is %A, %B %d, %Y.'
Today is Saturday, May 09, 2020.

How to ensure consistent usage between Linux and macOS?

One way to guarantee consistent behavior between Linux and macOS to formate a date is to make sure to always use the GNU date version of the date command line utility. It comes pre-installed by default on most Linux distributions, if not you will need to install the coreutils package. On Ubuntu/Debian you can run apt install coreutils.

The GNU coreutils can be installed on macOS using homebrew brew install coreutils. The GNU date command line will then be available as gdate on macOS.

What are the differences between Linux and Unix/macOS?

It is important to understand that the POSIX standard (POSIX.2) only specifies the -u option and the operand +format of the shell date utility. You can find the full specification in Posix 2 IEEE Std 1003.2. This means that any other options or operands in the date shell utility are systems specific implementation and may not be portable across platforms or environments.

The Unix and macOS date shell utility is compatible with the POSIX.2 standard and the -d, -f, -j, -n, -R, -r, -t, and -v options are all extensions to the standard.

The Linux date shell utility is the GNU date shell version which is also compatible with the POSIX.2 standard and also sets a large number of options that are all extensions to the standard. The Linux version of date is sometime called gdate when installed on different platforms.

⚠️ The non-standard options are not guaranteed to have the same behavior between Linux (GNU version) and Unix/macOS. A typical example would be the -d option which displays the time as described by a string on the Linux GNU version while it is used to set the kernel's value for daylight saving time on macOS.

The option -u will set the date in UTC instead of using the local time zone. Since it's part of the POSIX.2 specification both date version from Linux and Unix/macOS would display the same output for the command date -u.

Format a date on Linux using the GNU date command line

Before bash version 5, it was common to use the date '+%s' command to get the current Unix time, this should now be avoided since you can directly use the $EPOCHSECONDS shell variable. See What's New in GNU Bash 5?.

[me@linux ~]$ date '+%s' && echo $EPOCHSECONDS
1589053840
1589053840

Another variant has been to use date to get the real-time in microseconds, though GNU date will return nanoseconds while Bash provides $EPOCHREALTIME which is in microseconds directly. So, depending on the case you may have to do a simple division in bash to get the correct value. The example below can be easily ported to get milliseconds instead. See the man date (or man gdate) pages for the full list of formatting options.

[me@linux ~]$ echo $((`date '+%s%N'`/1000)) && echo $EPOCHREALTIME
1589053840916766
1589053840.918266

# Extra tips to get the same microseconds formatting
[me@linux ~]$ m=$((`date '+%s%N'`/1000)) && echo ${m:0:${#m}-6}.${m:${#m}-6} && echo $EPOCHREALTIME
1589053840.918266
1589053840.918266

# Example to get time with milliseconds and separated with a dot
[me@linux ~]$ m=$((`date '+%s%N'`/1000000)) && ${m:0:${#m}-3}.${m:${#m}-3}
1589054941.851

Another widely used option of GNU date is the -d option which makes handling dates extremely easy as you can use human-readable words to define a date. The option allows you to easily do operations on dates which is a big strength of the GNU date utility.

[me@linux ~]$ date -d 'last year'
Thu May  9 13:01:43 PDT 2019
[me@linux ~]$ date -d '90 days ago'
Sun Feb  9 12:03:34 PST 2020
[me@linux ~]$ date -d 'Feb 12 + 3 day' -u
Sat Feb 15 00:00:00 UTC 2020
[me@linux ~]$ date -d 'Feb 12 + 13 minutes' -u
Wed Feb 12 00:13:00 UTC 2020

Format a date on Unix/macOS using the BSD date command line

The macOS date shell command is quite more limited than the GNU version. Though, you can still use it for basic formatting. See the man date pages for the full list of formatting options. You can have the same behavior as GNU date -d option by using the -j (don't try to set date, display only) and -v (adjust date) options.

[me@macos ~]$ date '+%Y/%m/%d %H:%M:%S'
2020/05/09 13:20:2
[me@macos ~]$ date -j -v +3d -f "%b %d" "Feb 10"
Thu Feb 13 12:47:10 PST 2020

Display and Format dates with the GNU awk command line

GNU awk is often used to parse and process logs in an efficient way, luckily it can also be powerful when it comes to manipulating dates. Again, most of those features are extensions and are not specified by the POSIX standard.

mktime Turn a datespec (YYYY MM DD HH MM SS) into a timestamp
strftime Format a specified time to the given format as defined by strftime()
systime Return the Unix Time stamp (Epoch)
[me@macos ~]$ gawk 'BEGIN { print "Seconds since Epoch: " mktime("2020 05 09 14 47 27") }'
Seconds since Epoch: 1589060689

[me@macos ~]$ gawk 'BEGIN { print "Seconds since Epoch: " systime() }'
Seconds since Epoch: 1589060689

[me@macos ~]$ gawk 'BEGIN { print strftime("Today is %A, %B %d, %Y.", systime()) }'
Today is Saturday, May 09, 2020.

The example below from the gawk man pages show an example of awk reproducing the date command behavior and formatting.

#! /bin/sh
#
# date --- approximate the POSIX 'date' command

case $1 in
-u)  TZ=UTC0     # use UTC
     export TZ
     shift ;;
esac

gawk 'BEGIN  {
    format = PROCINFO["strftime"]
    exitval = 0

    if (ARGC > 2)
        exitval = 1
    else if (ARGC == 2) {
        format = ARGV[1]
        if (format ~ /^\+/)
            format = substr(format, 2)   # remove leading +
    }
    print strftime(format)
    exit exitval
}' "$@"

Display and Format dates by using the printf Bash builtin

The Bash printf builtin command support some date formats by using %(datefmt)T where datefmt is a format string passed to strftime and the corresponding argument is the Epoch time.

[me@linux ~]$ TZ=UTC printf "%(%F)T\n" 1589053840
2020-05-09

[me@linux ~]$ TZ=UTC printf "This date occurred in week %(%W)T of the year %(%Y)T\n" $EPOCHSECONDS
This date occurred in week 18 of the year 2020

Using printf makes the formatting to microseconds even simpler than when using the date command.

[me@linux ~]$ printf "%.3f\n" $EPOCHREALTIME
1589054941.851
[me@linux ~]$ printf "%.3f\n" $EPOCHREALTIME | tr -d .
1589054941851

Detailed Examples

How to set the date in shell?

The date command line allows you to also set your operating system date and time on Linux and Unix systems.

  • To set the date in shell using the date command line on Unix and macOS, use the -v option. Example: date -v "<DATETIME>".
  • To set the date in shell using the GNU version of the date command line on Linux, use the -s or --set option. Example: date -s "<DATETIME>".

⚠️ You should prefer to setup your system to use the ntp protocol to synchronize your clocks. Manually setting the date and time on your system is not reliable as time delays will be introduced fairly quickly. On Linux Ubuntu 20.04, you can use the command chronyd -q to force a one-time sync and chronyd -Q to only check the date and time for differences.

How to format a date in Bash?

The following examples use the shell date command line. The date command use case-sensitive format specifiers, so the uppercase or lowercase letters in format would have different results. In the below examples, using %M instead of %m would mean minutes instead of month.

Bash Date format MM-DD-YYYY

To format date in MM-DD-YYYY format, use the command date +%m-%d-%Y or printf "%(%m-%d-%Y)T\n" $EPOCHSECONDS.

Bash Date format DD-MM-YYYY

To format date in DD-MM-YYYY format, use the command date +%d-%m-%Y or printf "%(%d-%m-%Y)T\n" $EPOCHSECONDS.

Bash Date format YYYY-MM-DD

To format date in YYYY-MM-DD format, use the command date +%F or printf "%(%F)T\n" $EPOCHSECONDS. The %F option is an alias for %Y-%m-%d.

This format is the ISO 8601 format.

Bash date format options

Below is a list of common date format options and examples output.

Date Format Option Meaning Example Output
date +%c locale's date time Sat May 9 11:49:47 2020
date +%x locale's date 05/09/20
date +%X locale's time 11:49:47
date +%A locale's full weekday name Saturday
date +%B locale's full month name May
date +%m-%d-%Y MM-DD-YYYY date format 05-09-2020
date +%D MM/DD/YY date format 05/09/20
date +%F YYYY-MM-DD date format 2020-05-09
date +%T HH:MM:SS time format 11:44:15
date +%u Day of Week 6
date +%U Week of Year with Sunday as first day of week 18
date +%V ISO Week of Year with Monday as first day of week 19
date +%j Day of Year 130
date +%Z Timezone PDT
date +%m Month of year (MM) 05
date +%d Day of Month (DD) 09
date +%Y Year (YY) 2020
date +%H Hour (HH) 11
date +%H Hour (HH) in 24-hour clock format 11
date +%I Hour in 12-hour clock format 11
date +%p locale's equivalent of AM or PM AM
date +%P same as %p but in lower case am

You can get the full list of supported date format specifiers using the man date or man gdate commands.

How to add a day to a date in shell?

To get the date in bash shell and add a date, you can use the GNU date command as date -d 'Feb 12 +1 day' +%F which will output 2020-02-13. See above section on GNU date for more example on the -d option.

On macOS with the Unix date command, you would need to use the command as such date -j -v +1d -f "%b %d" "Feb 12" +%F.

How to get yesterday's date in shell?

To get yesterday's date in bash shell you can use the Linux GNU date version with date -d yesterday or the Unix/macOS date version using date -j -v -1d.

How to do date comparison in bash?

To compare two dates in bash, you can use the unix timestamp value of both date using the date command line or the printf method. You can also do a lexicographical comparison of the two dates string by using the double square bracket conditional construct [[..]].

# By comparing Unix Timestamp
[me@linux ~]$ firstDate=$(date -d 'Feb 12 UTC' +%s)
[me@linux ~]$ secondDate=$(date -d 'Feb 13 UTC' +%s)
[me@linux ~]$ if (($secondDate > $firstDate)); then echo "Second Date is more recent than First Date"; fi
Second Date is more recent than First Date

# By doing lexical comparion
[me@linux ~]$ firstDate=$(date -d 'Feb 12 UTC' +"%F %T")
[me@linux ~]$ secondDate=$(date -d 'Feb 13 UTC' +"%F %T")
[me@linux ~]$ if [[ $secondDate > $firstDate ]]; then echo "Second Date is more recent than First Date"; fi
Second Date is more recent than First Date

How to calculate the difference between two dates in shell?

There is a naive way to do this easily with any of the commands above which is to simply subtract both dates from their Unix timestamp value and then convert the seconds to hours or days as needed. For a Math in Bash refresher, see the post Performing Math Calculation In Bash.

⚠️ When using this naive date comparison method, make sure to always use the UTC standard for the date, to avoid troubles with daylight saving. Also, note that this is still a very naive way to diff two dates and it does not consider the more complex scenarios where you may require the support of leap seconds or leap years.

[me@linux ~]$ firstDate=$(date -d 'Feb 12 UTC' +%s)
[me@linux ~]$ secondDate=$(date -d 'Feb 13 UTC' +%s)
[me@linux ~]$ echo $firstDate $secondDate
1581494400 1581580800
[me@linux ~]$ echo "The difference is $(( (secondDate-firstDate) / 3600 )) hours"
The difference is 24 hours

How to calculate the time elapsed in Bash?

The simplest option is to use the special shell variable $SECONDS to get the amount of seconds elapsed. This special variable returns a count of the number of whole seconds since the shell or script has been running. The variable can be reset to zero or any other integer.

[me@linux ~]$ SECONDS=0; sleep 2; echo "Time elapsed since \$SECONDS was reset: $SECONDS seconds";
Time elapsed since $SECONDS was reset: 2 seconds

Alternatively, you can calculate the difference between two dates as described in the section How to calculate the difference between two dates?.

How to convert the Unix Timestamp to UTC in shell? (i.e. Unix to Date format)

The easiest way to convert a Unix Timestamp to UTC is to use GNU date with the @ feature and the -u option.

[me@linux ~]$ date -d @1547092066 -u
Thu Jan 10 03:47:46 UTC 2019

Another option would be to use the bash printf builtin and set the TZ environment variable to UTC. The %+ specifier uses the date and time format as in the date command line.

[me@linux ~]$ TZ=UTC printf "%(%+)T\n" 1547092066
Thu Jan 10 03:47:46 UTC 2019
Related linux posts that you may like...
How To Create Simple Menu with the Shell Select Loop?
The select loop is not a regular shell loop. It can be used in Bash to generate a simple menu from which a user can select numbered options.
What is the Right Way to Loop in Bash?
Looping over a list of numbers or words is a building block in shell scripts. Learn how to write Bash loops, including for loop, while loop, and until loop.
5 Mistakes To Avoid For Writing High-Quality Bash Comments
Adding comments in your Bash scripts is necessary to ensure maintainability over time. This post covers 5 Bash comments mistakes to avoid in your shell scripts.
How to Script Powerful Bash If Statement?
Learn how to script a Bash If statement with the then, else, and else if / elif clauses. This post covers the Bash conditional expressions, and how to avoid common pitfalls when using the Bash If statement.