Time zone and
daylight-saving
rules are controlled by individual
governments. They are sometimes changed with little notice, and their
histories and planned futures are often recorded only fitfully. Here
is a summary of attempts to organize and record relevant data in this
area.
Each main entry in the database represents a timezone
for a set of civil-time clocks that have all agreed since 1970.
Timezones are typically identified by continent or ocean and then by the
name of the largest city within the region containing the clocks.
For example, America/New_York
represents most of the US eastern time zone;
America/Phoenix represents most of Arizona, which
uses mountain time without daylight saving time (DST);
America/Detroit represents most of Michigan, which uses
eastern time but with different DST rules in 1975;
and other entries represent smaller regions like Starke County,
Indiana, which switched from central to eastern time in 1991
and switched back in 2006.
To use the database on a POSIX.1-2024
implementation set the TZ
environment variable to the location's full name,
e.g., TZ="America/New_York".
Associated with each timezone is a history of offsets from
Universal
Time (UT), which is Greenwich Mean
Time (GMT) with days beginning at midnight;
for timestamps after 1960 this is more precisely Coordinated
Universal Time (UTC).
The database also records when daylight saving time was in use,
along with some time zone abbreviations such as EST
for Eastern Standard Time in the US.
Downloading the tz database
The following shell commands download
the latest release's two
tarballs
to a GNU/Linux or similar host.
mkdir tzdb
cd tzdb
wget https://www.iana.org/time-zones/repository/tzcode-latest.tar.gz
wget https://www.iana.org/time-zones/repository/tzdata-latest.tar.gz
gzip -dc tzcode-latest.tar.gz | tar -xf -
gzip -dc tzdata-latest.tar.gz | tar -xf -
Alternatively, the following shell commands download the same
release in a single-tarball format containing extra data
useful for regression testing:
These commands use convenience links to the latest release
of the tz database hosted by the
Time Zone Database website
of the Internet Assigned Numbers
Authority (IANA).
Older releases are in files named
tzcodeV.tar.gz,
tzdataV.tar.gz, and
tzdb-V.tar.lz,
where V is the version.
Since 1996, each version has been a four-digit year followed by
lower-case letter (a through z,
then za through zz, then zza
through zzz, and so on).
Since version 2022a, each release has been distributed in
POSIX
ustar interchange format, compressed as described above;
older releases use a nearly compatible format.
Since version 2016h, each release has contained a text file named
"version" whose first (and currently only) line is the version.
Older releases are archived,
and are also available in an
FTP directory via a
less secure protocol.
Alternatively, a development repository of code and data can be
retrieved from GitHub via the shell
command:
Since version 2012e, each release has been tagged in development repositories.
Untagged commits are less well tested and probably contain
more errors.
After obtaining the code and data files, see the
README file for what to do next.
The code lets you compile the tz source files into
machine-readable binary files, one for each location. The binary files
are in a special format specified by
The
Time Zone Information Format (TZif)
(Internet RFC 9636).
The code also lets
you read a TZif file and interpret timestamps for that
location.
Changes to the tz code and data are often
propagated to clients via operating system updates, so
client tz data can often be corrected by
applying these updates. With GNU/Linux and similar systems, if your
maintenance provider has not yet adopted the
latest tz data, you can often short-circuit
the process by tailoring the generic instructions in
the tz README file and installing the latest
data yourself. System-specific instructions for installing the
latest tz data have also been published
for AIX,
Android,
ICU,
IBM
JDK,
Joda-Time, MySQL,
Noda Time, and OpenJDK/Oracle JDK.
As discussed in
"How
Time Zones Are Coordinated", the time zone database relies on
collaboration among governments, the time zone database volunteer
community, and data distributors downstream.
If your government plans to change its time zone boundaries or
daylight saving rules, please send email to tz@iana.org well in advance,
as this will lessen confusion and will coordinate updates to many cell phones,
computers, and other devices around the world.
In your email, please cite the legislation or regulation that specifies
the change, so that it can be checked for details such as the exact times
when clock transitions occur.
It is OK if a rule change is planned to affect clocks
far into the future, as a long-planned change can easily be reverted
or otherwise altered with a year's notice before the change would have
affected clocks.
There is no fixed schedule for tzdb releases.
However, typically a release occurs every few months.
Many downstream timezone data distributors wait for
a tzdb release before they produce an update
to time zone behavior in consumer devices and software products.
After a release, various parties must integrate, test,
and roll out an update before end users see changes.
These updates can be expensive, for both the quality
assurance process and the overall cost of shipping and installing
updates to each device's copy of tzdb.
Updates may be batched with other updates and may take substantial
time to reach end users after a release.
Older devices may no longer be supported and thus may never be updated,
which means they will continue to use out-of-date rules.
For these reasons any rule change should be promulgated at least a
year before it affects how clocks operate; otherwise, there is a good
chance that many clocks will be wrong due to delays in propagating updates,
and that residents will be confused or even actively resist the change.
The shorter the notice, the more likely clock problems will arise; see "On
the Timing of Time Zone Changes" for examples.
Commentary on the tz database
The article
tz database is
an encyclopedic summary.
Although some of these do not fully support
tz data, in recent tzdb
distributions you can generally work around compatibility problems by
running the command make rearguard_tarballs and compiling
from the resulting tarballs instead.
Vzic is a C
program that compiles
tz source into iCalendar-compatible VTIMEZONE files.
Vzic is freely
available under the GNU
General Public License (GPL).
DateTime::TimeZone
contains a script parse_olson that compiles
tz source into Perl
modules. It is part of the Perl DateTime Project,
which is freely
available under both the GPL and the Perl Artistic
License. DateTime::TimeZone also contains a script
tests_from_zdump that generates test cases for each clock
transition in the tz database.
International Components for
Unicode (ICU) contains C/C++ and Java
libraries for internationalization that
has a compiler from tz source
and from CLDR data
(mentioned below)
into an ICU-specific format.
ICU is freely available under a
BSD-style license.
The Tzdata package for
the Elixir language downloads
and compiles tz source and exposes APIs for use. It is
freely available under the MIT license.
Joda-Time – Java date
and time API contains a class
org.joda.time.tz.ZoneInfoCompiler that compiles
tz source into a binary format. It inspired
Java 8 java.time, which its users should migrate to once
they can assume Java 8 or later. It is available under the Apache License.
IANA Updater and ZIUpdater
are alternatives to TZUpdater. IANA Updater's license is unclear;
ZIUpdater is licensed under the GPL.
ICU (mentioned above) contains compilers and
Java-based libraries.
Noda Time – Date and
time API for .NET
is like Joda-Time and Time4J, but for the .NET framework instead of Java.
It is freely available under the Apache License.
Many modern
JavaScript
runtimes support tz natively via the
timeZone option of Intl.DateTimeFormat.
This can be used as-is or with most of the following libraries,
many of which also support runtimes lacking the timeZone option.
The date-fns
library manipulates timezone-aware timestamps in browsers and
in Node.js.
It is freely available under the MIT license.
Day.js is a
minimalist replacement for the date and time API of
the now-legacy Moment.js date
manipulation library.
It is freely available under the MIT license.
Luxon improves
timezone support for the Intl API.
It is freely available under the MIT license.
Moment Timezone is a
Moment.js plugin.
It is freely available under the MIT license.
Timezone is a
JavaScript library that supports date arithmetic that is time zone
aware. It is freely available under the MIT license.
@tubular/time
supports live tzdb updates,
astronomical and atomic time, a command-line interface,
and full TypeScript.
Its companion @tubular/time-tzdb
can generate TZif and other files, and a companion website
Timezone Database Explorer lets you
convert timestamps, view transition histories, and download code and data.
It is freely available under the MIT license.
The Chronos Date/Time
Library is
a Smalltalk class
library that compiles tz source into a time
zone repository whose format
is either proprietary or an XML-encoded
representation.
Tcl
contains a developer-oriented parser that compiles tz
source into text files, along with a runtime that can read those
files. Tcl is freely available under a BSD-style
license.
Other TZif readers
The GNU C
Library
has an independent, thread-safe implementation of
a TZif file reader.
This library is freely available under the LGPL
and is widely used in GNU/Linux systems.
GNOME's
GLib has
a TZif file reader written in C that
creates a GTimeZone object representing sets
of UT offsets.
It is freely available under the LGPL.
The
BDE Standard Library's
baltzo::TimeZoneUtil component contains a C++
implementation of a TZif file reader. It is freely available under
the Apache License.
CCTZ is a simple C++
library that translates between UT and civil time and
can read TZif files. It is freely available under the Apache
License.
The
posix_tz_db
package contains Python code
to generate CSV and JSON tables that map
tz settings to proleptic TZ approximations.
For example, it maps "Africa/Cairo"
to "EET-2EEST,M4.5.5/0,M10.5.4/24",
an approximation valid for Cairo timestamps from 2023 on.
This can help porting to platforms that support only proleptic TZ.
The package is freely available under the MIT license.
Timelib is a C
library that reads TZif files and converts
timestamps from one time zone or format to another.
It is used by PHP,
HHVM,
and MongoDB.
It is freely available under the MIT license.
Tcl, mentioned above, also contains a
TZif file reader.
DateTime::TimeZone::Tzfile
is a TZif file reader written in Perl.
It is freely available under the same terms as Perl
(dual GPL and Artistic license).
Python has a zoneinfo.ZoneInfo
class that reads TZif data and creates objects
that represent tzdb timezones.
Python is freely available under the
Python Software Foundation
License.
A companion PyPI module
tzdata
supplies TZif data if the underlying system data cannot be found;
it is freely available under the Apache License.
The
public-domain tz.js
library contains a Python tool that
converts TZif data into
JSON-format data suitable for use
in its JavaScript library for time zone conversion. Dates before 1970
are not supported.
The timezone-olson
package contains Haskell code that
parses and uses TZif data. It is freely
available under a BSD-style license.
Oracle
Java contains a copy of a subset of a recent
tz database in a
Java-specific format.
Other time zone databases
Time-zone Atlas
is Astrodienst's Web version of Shanks and Pottenger's out-of-print
time zone history atlases
for the US and
for the world.
Although these extensive atlases
were
sources for much of the older tz data,
they are unreliable as Shanks appears to have
guessed many UT offsets and transitions. The atlases cite no
sources and do not indicate which entries are guesswork.
The Standard
Schedules Information Manual of the
International Air Transport Association
gives current time zone rules for airports served by commercial aviation.
World Time Zone Map
with current time
has several fancy time zone maps; it covers Russia particularly well.
The maps' pictorial quality is not quite as good as the
CIA's
but the maps are more up to date.
How
much is time wrong around the world? maps the difference between
mean solar and standard time, highlighting areas such as western China
where the two differ greatly. It's a bit out of date, unfortunately.
Time zone boundaries
Geographical boundaries between timezones are available
from several Internet
geolocation
services and other sources.
Timezone
Boundary Builder extracts
Open Street Map data to build
boundaries of tzdb timezones.
Its code is freely available under the MIT license, and
its data entries are freely available under the
Open Data Commons
Open Database License. The borders appear to be quite accurate.
Its main web page lists more than twenty libraries
for looking up a timezone name from a GPS coordinate.
A ship within the territorial
waters of any nation uses that nation's time. In international
waters, time zone boundaries are meridians 15° apart, except that
UT−12 and UT+12 are each 7.5°
wide and are separated by
the 180° meridian (not by the International Date Line, which is
for land and territorial waters only). A captain can change ship's
clocks any time after entering a new time zone; midnight changes are
common.
The Department of Transportation's Recent
Time Zone Proceedings lists changes to
official written time zone boundaries, and its Time
Zones dataset maps current boundaries.
These boundaries are only for standard time, so the current map puts
all of Arizona in one time zone even though part of Arizona
observes DST and part does not.
Uruguay
The Oceanography, Hydrography, and Meteorology Service of the Uruguayan
Navy (SOHMA) publishes an annual almanac
(in Spanish).
Costs and benefits of time shifts
Various sources argue for and against daylight saving time and time
zone shifts, and many scientific studies have been conducted. This
section summarizes reviews and position statements based on
scientific literature in the area.
Havranek T, Herman D, Irsova D.
Does
daylight saving save electricity? A meta-analysis.
Energy J. 2018;39(2):35–61.
doi:10.5547/01956574.39.2.thav.
This analyzes research literature and concludes, "Electricity savings
are larger for countries farther away from the equator, while
subtropical regions consume more electricity because of DST."
Roenneberg T, Wirz-Justice A, Skene DJ et al.
Why
should we abolish Daylight Saving Time?J Biol Rhythms. 2019;34(3):227–230.
doi:10.1177/0748730419854197.
The Society for Research on Biological Rhythms
opposes DST changes and permanent DST,
and advocates that governments adopt
"permanent Standard Time for the health and safety of their citizens".
Precision timekeeping
The
Science of Timekeeping is a thorough introduction
to the theory and practice of precision timekeeping.
The Huygens
family of software algorithms can achieve accuracy to a few tens of
nanoseconds in scalable server farms without special hardware.
The Precision
Time Protocol (IEEE 1588)
can achieve submicrosecond clock accuracy on a local area network
with special-purpose hardware.
Timezone
Options for DHCP
(Internet RFC 4833)
specifies a DHCP
option for a server to configure
a client's time zone and daylight saving settings automatically.
Time
Scales describes astronomical time scales like
TDT,
TCG, and
TDB.
The IAU's SOFA
collection contains C and Fortran
code for converting among time scales like
TAI,
TDB, TDT and
UTC. It is freely available under the
SOFA license.
Mars24 Sunclock
– Time on Mars describes Airy Mean Time (AMT) and the
diverse local time
scales used by each landed mission on Mars.
LeapSecond.com is
dedicated not only to leap seconds but to precise time and frequency
in general. It covers the state of the art in amateur timekeeping, and
how the art has progressed over the past few decades.
The rules for leap seconds are specified in Annex 1 (Time scales) of Standard-frequency
and time-signal emissions, International Telecommunication Union –
Radiocommunication Sector (ITU-R) Recommendation TF.460-6 (02/2002).
IERS
Bulletins contains official publications of the International
Earth Rotation and Reference Systems Service, which decides when leap
seconds occur. The tz code and data support leap seconds
via an optional "right" configuration where a computer's internal
time_t integer clock counts every TAI second,
as opposed to the default "posix" configuration
where the internal clock ignores leap seconds.
The two configurations agree for timestamps starting with 1972-01-01 00:00:00
UTC (time_t 63 072 000) and diverge for
timestamps starting with time_t 78 796 800,
which corresponds to the first leap second
1972-06-30 23:59:60 UTC in the "right" configuration,
and to
1972-07-01 00:00:00 UTC in the "posix" configuration.
In practice the two configurations also agree for timestamps before
1972 even though the historical situation is messy, partly because
neither UTC nor TAI
is well-defined for sufficiently old timestamps.
The
NTP Leap Second File covers the text file
leap-seconds.list, which lists the currently known leap seconds.
The IERS maintains this file, and a copy is distributed by
tzdb for use by NTP implementations like
classic
ntpd
and NTPsec.
The tz database also distributes leap second
information in a differently-formatted leapseconds text file,
as well as in the "right" configuration in binary form; for
example, right/UTC can be used
by chrony,
another NTP implementation.
Leap Smear
discusses how to gradually adjust POSIX clocks near a
leap second so that they disagree with UTC by at most a
half second, even though every POSIX minute has exactly
sixty seconds. This approach works with the default tz
"posix" configuration, is supported by
the abovementioned NTP implementations, supports conversion between
UTC and smeared POSIX timestamps, and is used by major
cloud service providers. However, according to
§3.7.1 of
Network Time Protocol Best Current Practices
(Internet RFC 8633), leap smearing is not suitable for
applications requiring accurate UTC or civil time,
and is intended for use only in single, well-controlled environments.
The Unicode Common Locale Data
Repository (CLDR) Project has localizations for time
zone names, abbreviations, identifiers, and formats. For example, it
contains French translations for "Eastern European Summer Time",
"EEST", and
"Bucharest". Its
by-type
charts show these values for many locales. Data values are available in
both LDML
(an XML format) and JSON.
Alphabetic time zone abbreviations should not be used as unique
identifiers for UT offsets as they are ambiguous in
practice. For example, in English-speaking North America
"CST" denotes 6 hours behind UT,
but in China it denotes 8 hours ahead of UT,
and French-speaking North Americans prefer
"HNC" to
"CST". The tz
database contains English abbreviations for many timestamps;
unfortunately some of these abbreviations were merely the database maintainers'
inventions, and these have been removed when possible.
Numeric time zone abbreviations typically count hours east of
UT, e.g., +09 for Japan and
−10 for Hawaii. However, POSIX proleptic
TZ settings use the opposite convention.
For example, one might use TZ="JST-9" and
TZ="HST10"
for Japan and Hawaii, respectively. If the
tz database is available, it is usually better to use
settings like TZ="Asia/Tokyo" and
TZ="Pacific/Honolulu" instead, as this should avoid
confusion, handle old timestamps better, and insulate you better from
any future changes to the rules. One should never set
POSIX TZ to a value like
"GMT-9", though, since this would incorrectly imply that
local time is nine hours ahead of UT and the time zone
is called "GMT".