The tz database: raw text rules compiled by zic into binary zone files

What the README disclaims before it describes anything

The tz distribution's README opens with a quotation from a 1950s Bell System film, then describes what the database is: code and data representing the history of local time for many representative locations around the globe, updated periodically to reflect changes made by political bodies to time zone boundaries, UTC offsets, and daylight-saving rules.

Then it lists goals, and the first one is a qualification. The database aims to provide a compendium of data about the history of civil time that is useful even if not 100 percent accurate. The second goal is to give an idea of the variety of local time rules that have existed in the past and thus may be expected in the future. The third is to test the generality of the local time rule description system.

And then the sentence that matters most for anyone building on it: the information in the time zone data files is by no means authoritative, and fixes and enhancements are welcome, with a pointer to the `CONTRIBUTING` file.

That is not false modesty. It is the project's scope statement. tzdb is a compendium maintained by volunteers, not a legal record certified by any jurisdiction. If your use case needs the actual law of a specific jurisdiction on a specific date, this is the wrong authority, and the project tells you so before you read a single data file.

The Makefile's assumptions are the real platform contract

The most operationally useful file in the repository is the Makefile, and it starts by declaring its standards.

The first non-comment line is `.POSIX:`, and the comment next to it requests POSIX conformance. By default, builds of code and data assume POSIX.1-2001 or later, and that assumption can be relaxed by tailoring the build. On older platforms the comment suggests scrounging for POSIX conformance, giving Solaris 10 with Sun Studio 12 as a worked example and pointing at `make CC=c99` with a specific PATH.

The build tool requirements are stated too. Reproducible builds of distribution tarballs need a copy of the Git repository, and assume the behaviour of Git 2.7.0, GNU Coreutils 6.3, GNU Tar 1.14 and GnuPG 1.4, or later versions of each.

Two named variables are set at the top. `PACKAGE` is `tzcode`, and `VERSION` is `unknown` by default, overridden in the `tarballs` rule. The bug report address is `[email protected]`. A `DATAFORM` macro selects the data format.

The comment about software bill of materials is worth reading twice. The Makefile states that although tzdb does not come with a software bill of materials, you should be able to construct one based on the information given, your platform, and the way you use the Makefile. That is an unusually direct statement about what a supply-chain reviewer has to do themselves.

Tuning is done by passing macros on the command line rather than editing the file, and the Makefile gives the pattern: `make CFLAGS='-O2 -DHAVE_GETTEXT=0'`, described as appropriate for a GNU/Linux system needing more optimization than default and no gettext internationalisation of diagnostics.

Installing into a directory and proving it with zdump

The README's own instructions are short enough to quote in full, and they are the sequence to follow.

Acquire the code and data. The README points at the IANA page for how to acquire it and at the file `tz-link.html` in the distribution.

Read the leading comments in the file `Makefile` and make any changes needed for your system, especially when using a platform other than current GNU/Linux. This step is not optional in the README's phrasing, and skipping it is how a build ends up subtly non-POSIX.

Then run the build with your own installation directory substituted for `$HOME/tzdir`:

make TOPDIR="$HOME/tzdir" install
"$HOME/tzdir/usr/bin/zdump" -v America/Los_Angeles

That second command is the verification step, and it is the part people skip. `zdump -v` prints the zone's transition times and offsets across a range, so you can confirm the compiled binary matches your expectation for a location you already know rather than trusting that the build succeeded. Note that installing into `$HOME/tzdir` gives you binaries under `usr/bin`, mirroring the eventual system layout, which is what makes the `zdump` path read that way.

For learning how to read the data files themselves, the README points at `tz-how-to.html` for examples.

Zone names and rule files are both in the root directory

The top-level file listing is the clearest description of how the database is organised, because the geographic files sit next to the C sources that consume them.

The rule files are named for continents and oceans: `africa`, `antarctica`, `asia`, `australasia`, `europe`, `northamerica`, `southamerica`, `etcetera`, and `backward` and `backzone` for zones that moved or are deprecated. `factory` holds the template from which zones are instantiated.

The compiled-consumption side is C source and man pages: `asctime.c`, `date.c`, `difftime.c`, `localtime.c`, `strftime.c`, and `zdump.c`, with a shared `private.h` and a `tzfile.h`. Each tool has its man page: `date.1`, `zic.8`, `zdump.8`, `tzselect.8`, `tzfile.5`, and `newctime.3`, `newstrftime.3`, `newtzset.3`, `time2posix.3`.

Zone identifier tables come in generations: `zone.tab`, `zone1970.tab` and `zonenow.tab`, plus `iso3166.tab` for the country codes. `calendars` and `leapseconds.awk` handle calendar and leap-second data, and there is a `leap-seconds.list` file.

Then the maintenance tooling, which is the part that reveals how the data is validated: `checklinks.awk`, `checknow.awk`, `checktab.awk`, `ziguard.awk` and `zishrink.awk`, plus `workman.sh`, `tzselect.ksh` and `tz-art.html`. Documentation includes `theory.html` for the underlying model and `tz-how-to.html` for usage.

Two roots files describe the project's own governance: `CONTRIBUTING` for how corrections are proposed and `SECURITY` for reporting. `NEWS` is the changelog and `LICENSE` carries the licensing split.

Licensing is per-file, not per-project

The licensing statement is short and precise, and it is the kind of precision that matters when tz data is vendored into a product.

The README states that the README file itself is in the public domain, so clarified as of 2009-05-17 by Arthur David Olson. The other files in the distribution are either public domain or BSD licensed, with the LICENSE file holding the details.

So there is no single identifier to cite. You have to read `LICENSE` to know which files fall under which grant, which is why the repository's license field is recorded as a custom licence GitHub cannot classify rather than as MIT or BSD-2-Clause.

For redistribution, the practical requirement is that the LICENSE file travels with whatever you ship, and that you check it per file rather than assuming the whole tree shares one term. The README also credits Arthur David Olson as the project's founder and first maintainer, and closes the credits by noting that none of the contributors named are responsible for remaining errors, which is the accuracy disclaimer restated in a different place.

One more operational file exists that is easy to miss: `SECURITY` at the root. The README does not describe it, but its presence means vulnerability reports have a documented path that is separate from `BUGEMAIL`.

Where the tz database is the wrong tool

Three mismatches are worth naming.

First, if you need legal certainty about a jurisdiction's rules, this is the wrong source, and the project says so. The stated goal is a compendium useful even if not 100 percent accurate. If a dispute turns on whether an offset was correct at a specific instant, the contributing volunteer process is not the evidentiary standard you want.

Second, if you need current time and nothing else, tzdb is enormous overkill. A fixed UTC offset or a platform's own time zone database answers the question without compiling rule files or shipping binary TZif data. tzdb earns its weight when you need the history or the future transitions, not when you need today's offset.

Third, if you cannot run the build. The data files are human-readable sources and the consumer needs the compiled TZif output, so using tzdb means either accepting a distribution's compiled files or building it yourself with a POSIX.1-2001 or later environment. On an exotic platform with no POSIX conformance, the Makefile tells you to scrounge for it.

The alternative worth comparing is a maintained library database such as the one bundled with your runtime or operating system, which is already compiled, already updated on a schedule, and carries the same accuracy caveat without the build step. The difference in approach is ownership: tzdb gives you the primary source and the ability to patch a data file yourself when a jurisdiction changes its rules and the next release has not caught up, which for a system where correctness is a legal question is sometimes the whole point.

Editorial conclusion

Adopt the tz database, which most systems already vendor, if you need historical local time for a named location rather than a fixed offset, because its whole value is expressing political changes to boundaries and daylight-saving rules as data instead of as assumptions in code. Do not adopt it as a source of legal authority on what time a jurisdiction observed; the README states the information in the time zone data files is by no means authoritative, and that it aims for a compendium useful even if not 100 percent accurate. Verify three things before you build on it: that your acquisition path matches your platform, since the README says to read the leading comments in `Makefile` and make changes needed for your system, especially when not using current GNU/Linux; that `make TOPDIR="$HOME/tzdir" install` produces a `zdump` that answers correctly for a location you already know, verified with `"$HOME/tzdir/usr/bin/zdump" -v America/Los_Angeles`; and that you have read `CONTRIBUTING` before filing a correction, because the README asks for contributions in a specific way. The last push was on 2026-10-13. Licensing is split: the README file itself is in the public domain as clarified on 2009-05-17, and the other files are public domain or BSD licensed per the LICENSE file.

Frequently asked questions

Official sources

1. eggert/tz on GitHub
2. Issues
3. Project website
4. README