Time zone and daylight saving time data

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.

Outline

The 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.

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:

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.

Changes to the 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.

Coordinating with governments and distributors

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.

Commentary on the tz database

Web sites using recent versions of the tz database

These are listed roughly in ascending order of complexity and fanciness.

Network protocols for tz data

Other tz compilers

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.

Other TZif readers

Other tz-based time zone software

Other time zone databases

Maps

Time zone boundaries

Geographical boundaries between timezones are available from several Internet geolocation services and other sources.

Civil time concepts and history

National histories of legal time

Australia
The Parliamentary Library commissioned a research paper on daylight saving time in Australia. The Bureau of Meteorology publishes a list of Implementation Dates of Daylight Savings Time within Australia.
Belgium
The Royal Observatory of Belgium maintains a table of time in Belgium (in Dutch and French).
Brazil
The Time Service Department of the National Observatory records Brazil's daylight saving time decrees (in Portuguese).
Canada
National Research Council Canada publishes current and some older information about time zones and daylight saving time.
Chile
The Hydrographic and Oceanographic Service of the Chilean Navy publishes a history of Chile's official time (in Spanish).
China
The Hong Kong Observatory maintains a history of summer time in Hong Kong, and Macau's Meteorological and Geophysical Bureau maintains a similar history for Macau. Unfortunately the latter is incomplete and has errors.
Czech Republic
When daylight saving time starts and ends (in Czech) summarizes and cites historical DST regulations.
Germany
The National Institute for Science and Technology maintains the Realisation of Legal Time in Germany.
Israel
Israel Timezone Files lists official time-change announcements and laws since 1940, almost all in Hebrew.
Malaysia
See Singapore below.
Mexico
The Investigation and Analysis Service of the Mexican Library of Congress has published a history of Mexican local time (in Spanish).
Netherlands
Legal time in the Netherlands (in Dutch) covers the history of local time in the Netherlands from ancient times.
New Zealand
The Department of Internal Affairs maintains a brief History of Daylight Saving.
Palestine
The Ministry of Telecom and IT publishes a history of clock changes (in Arabic).
Portugal
The Lisbon Astronomical Observatory publishes a history of legal time (in Portuguese).
Singapore
Why is Singapore in the "Wrong" Time Zone? details the history of legal time in Singapore and Malaysia.
United Kingdom
History of legal time in Britain discusses in detail the country with perhaps the best-documented history of clock adjustments.
United States
The Department of Transportation's Recent Time Zone Proceedings lists changes to time zone boundaries.
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.

Precision timekeeping

Time notation

See also