GNU Date - timezone conversions
When it is Monday, Sep 18th 2017, 6am in Sydney (Australia),
what is the time in Toronto (Canada)?
date can answer that question:
$ TZ=America/Toronto date -d 'TZ="Australia/Sydney" 2017-09-18 6am' Sun Sep 17 16:00:00 EDT 2017
In Toronto, it will be Sunday, Sep 17th, 4pm (16:00).
Use the following syntax to convert time and dates between time zones:
output timezone input timezone input date/time ------------------ -------------------- --------------- TZ=America/Toronto date -d 'TZ="Australia/Sydney" 2017-09-18 6am'
Below are more details, examples and use cases.
Current time in a different time zone
What is the current time in Tokyo (Japan)?
$ TZ=Asia/Tokyo date Mon Sep 18 06:46:04 JST 2017 # Your results will vary based on the current time
To print the current time and date in a different time zone,
simply set the
TZ environment variable.
Convert a different timezone to local time
When it’s 7am in Singapore, what is the local time here?
$ date -d 'TZ="Asia/Singapore" 2017-09-17 7am' Sat Sep 16 17:00:00 MDT 2017 # Your result will vary based on your local timezone
To convert another timezone to your local time zone,
set the input
TZ variable inside the
-d date string argument.
TZenvironment variable should contain a valid time zone name. See next section to find out the time zones available on your system.
TZdefinition (the input timezone) must be surrounded by double-quotes. Without them,
datewill fail to parse the time zone string:
$ TZ=America/Toronto date -d 'TZ=Australia/Sydney 2017-09-18 6am' # missing double-quotes around Australia/Sydney date: invalid date `TZ=Australia/Sydney 2017-09-18 6am'
The argument to the
-dparameter is a string, and must be quoted. If quoting the entire parameter with double-quotes, be sure to escape the inner quotes:
$ TZ=America/Toronto date -d "TZ=\"Australia/Sydney\" 2017-09-18 6am" Sun Sep 17 16:00:00 EDT 2017
Invalid or non-existing timezone names are silently ignored and treated as UTC (time zone 00:00, similar to GMT+0). This behaviour is required by POSIX. When getting unexpected results, be sure to check for timezone typos:
$ TZ=America/newyork date ## 'newyork' is not a valid timezone name Sun Sep 17 21:58:49 America 2017 ## result is incorrect $ TZ=America/New_York date ## 'New_York' is the correct timezone name, Sun Sep 17 17:58:55 EDT 2017 ## Using the file /usr/share/zoneinfo/America/New_York
These timezone conversion strings require GNU
dateis installed by default on most GNU/Linux distributions (e.g. Debian,Ubuntu,CentOS,RedHat,Fedora,Gentoo). It is not available by default on Mac OS X, FreeBSD, OpenBSD, etc. To install GNU date on MacOS X, consider using HomeBrew.
Available Time zones
On most Unix systems, the available time zones are stored as files
$ ls /usr/share/zoneinfo/ Africa Egypt Hongkong Mexico ROC America Eire HST MST ROK Antarctica EST Iceland MST7MDT Singapore Arctic EST5EDT Indian Navajo SystemV Asia Etc Iran NZ Turkey Atlantic Europe iso3166.tab NZ-CHAT UCT Australia Factory Israel Pacific Universal Brazil GB Jamaica Poland US Canada GB-Eire Japan Portugal UTC CET GMT Kwajalein posix WET Chile GMT0 leap-seconds.list posixrules W-SU CST6CDT GMT-0 Libya PRC Zulu Cuba GMT+0
Inside each sub-directory (e.g.
America) are a list of locations which
can be used as the timezone name:
$ ls /usr/share/zoneinfo/America/ Adak Anchorage Anguilla Antigua Araguaina Argentina Aruba ...
These files originate from the TZ Database maintained by Paul Eggert.
Other (less recommended) alternative syntaxes
Timezone abbreviations (e.g. “EST”, “EDT”) are not recommended as they are ambiguous between different regions:
$ TZ=Asia/Tokyo date -d '2017-11-05 6am EST' # NOT recommended Sun Nov 5 20:00:00 JST 2017
For example, “IST” could mean Irish Standard Time (UTC+1) or India Standard Time (UTC+5:30).
Additionally, using timezone abbreviations requires you to know if a region is using daylight saving time (DST) or not.
For example, on November 4th, 2015, was New York using EST (Eastern Standard Time, UTC-5) or EDT (Eastern Daylight saving time, UTC-4)? (For the answer, see here).
Using the appropriate timezone location (e.g.
EDT/EST ensures the correct daylight-saving-time setting
is used (as the TZ database is routinely updated with the latest
up-to-date information for each country).
Explicit zone hours are not recommended, as they ignore possible daylight-saving-time changes:
$ TZ=UTC4 date -d '2017-09-16 06:00+10' # NOT recommended Fri Sep 15 16:00:00 UTC 2017
While the above syntax is valid, it is not recommended. It converts the input date ‘2017-09-16 6am in timezone UTC+10’ (matching Sydney, Australia) to UTC-4 (matching Toronto, Canada), and returns the correct time (4pm/16:00 in Toronto). This conversion is correct only while Sydney uses Australian Eastern Standard Time (AEST) and Ontario uses Eastern Daylight Time (EDT).
Using explicit timezone hours ignores daylight saving changes. Daylight saving time changes are quite fluid, and many time depend on local politics. For example, the Canadian province Alberta is considering to do away with annual daylight saving time changes completely.
If such changes were to happen, the TZ database will be updated
accordingly and using
TZ=America/Edmonton timezone will use the
correct value (depending on the year and date, including past years
which still used daylight saving time).
More to follow
Stay tuned for more about
datein shell scripting and pipeline automation
- Date artihmetics
- The new
Follow me at @AGordonX for more articles (questions and topic requests are welcomed).