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.
tz
database
The public-domain
time zone database contains code and data
that represent the history of local time
for many representative locations around the globe.
It is updated periodically to reflect changes made by political bodies
to time zone boundaries and daylight saving rules.
This database (known as tz
,
tzdb
, or zoneinfo
)
is used by several implementations,
including
the
GNU
C Library (used in
GNU/Linux),
Android,
FreeBSD,
NetBSD,
OpenBSD,
ChromiumOS,
Cygwin,
MariaDB,
MINIX,
musl libc,
MySQL,
webOS,
AIX,
iOS,
macOS,
Microsoft Windows,
OpenVMS,
Oracle Database, and
Oracle Solaris.
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.
tz
databaseThe 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:
wget https://www.iana.org/time-zones/repository/tzdb-latest.tar.lz
lzip -dc tzdb-latest.tar.lz | tar -xf -
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:
git clone https://github.com/eggert/tz
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 8536).
The code also lets
you read a TZif file and interpret timestamps for that
location.
tz
database
The tz
code and data
are by no means authoritative. If you find errors, please
email changes to [email protected]
,
the time zone mailing list. See
the mailing
list's main page to subscribe or to browse its archive of old messages.
Metadata for mailing list
discussions and corresponding data changes can be
generated automatically.
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.
Since version 2013a,
sources for the tz
database have been
UTF-8
text files
with lines terminated by LF,
which can be modified by common text editors such
as GNU Emacs,
gedit, and
vim.
Specialized source-file editing can be done via the
Sublime
zoneinfo package for Sublime Text and the VSCode
zoneinfo extension for Visual
Studio Code.
For further information about updates, please see
Procedures for
Maintaining the Time Zone Database (Internet RFC 6557).
More detail can be
found in Theory and pragmatics of the
tz
code and data.
A0 TimeZone Migration
displays changes between recent tzdb
versions.
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 [email protected]
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.
tz
databasetz
database format.tz
databaseThese are listed roughly in ascending order of complexity and fanciness.
tzdb
-derived data in
CSV and
in SQL form.TZ
values directly.tz
datatz
compilersAlthough 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.
tz
source into iCalendar-compatible VTIMEZONE files.
Vzic is freely
available under the GNU
General Public License (GPL).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.std::chrono
API
that is a standard part of C++.
It is freely available under the
MIT license.tz
source
and from CLDR data
(mentioned below)
into an ICU-specific format.
ICU is freely available under a
BSD-style license.tz
source and exposes APIs for use. It is
freely available under the MIT license.tz
source into the format used by
OpenJDK and
Oracle JDK.
Although its source code is proprietary, its executable is available under the
Java SE
Timezone Updater License Agreement.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.tz
source into a binary format.
Time4A is available under the Apache License and Time4J is
available under the GNU Lesser
General Public License (LGPL).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.
Intl.DateTimeFormat
timezone polyfill
is freely available under a BSD-style license.Intl
API.
It is freely available under the MIT license.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.Temporal
objects let programs access an abstract view of
tzdb
data, and are designed to replace JavaScript's
problematic Date
objects when working with dates and times.
tz
source into
Julia. It is freely available
under the MIT license.tz
source into
Object Pascal
as compiled by Delphi
and FPC.
It is freely available under a BSD-style license.tz
source into
Python.
It is freely available under a BSD-style license.
In code that can assume Python 3.6 or later it is largely superseded; see pytz:
The Fastest Footgun in the West.tz
source into
Ruby.
It is freely available under the MIT license.tz
source into a time
zone repository whose format
is either proprietary or an XML-encoded
representation.tz
source into text files, along with a runtime that can read those
files. Tcl is freely available under a BSD-style
license.GTimeZone
object representing sets
of UT offsets.
It is freely available under the LGPL.baltzo::TimeZoneUtil
component contains a C++
implementation of a TZif file reader. It is freely available under
the Apache License.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.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.tz
-based time zone softwaretz
database in a
Go-specific format.tz
data and CLDR
data (mentioned below) used by the
Windows Runtime /
Universal Windows Platform classes
DateTimeFormatter
and
Calendar
.
Exploring
Windows Time Zones with System.TimeZoneInfo
describes
the older, proprietary method of Microsoft Windows 2000 and later,
which stores time zone data in the
Windows Registry. The
Zone →
Tzid table or XML
file of the CLDR data maps proprietary zone IDs
to tz
names.
These mappings can be performed programmatically via the TimeZoneConverter .NET library,
or the ICU Java and C++ libraries mentioned above.
tz
database in a
Java-specific format.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.tztab
(4) format.Geographical boundaries between timezones are available from several Internet geolocation services and other sources.
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.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.
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.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.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.tzdb
timezone of a timestamp
via suffixes like "[Asia/Tokyo]
".
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.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".