Would you prefer a timezone expert do this for you?

Subscribers click here.

How-To Guides

Issue Tracker

Need more help? Learn about
Oracle Java Support subscriptions

How to Use the TZUpdater "-l" Option to Add New Timezone Data to JDK or JRE Installations

Table of Contents


Applies To

Java SE JDK and JRE - Version 7 and later
Information in this document applies to any platform.


1 Introduction

You may have noticed that Oracle no longer provides a new TZUpdater tool update for every timezone update from the Standards body, ICANN / IANA. This is because, in 2015, Oracle released TZUpdater version 2.0, which provides a new feature to access the latest timezone data directly from IANA or ICANN. You no longer need to wait for a new version of the TZUpdater tool in order to add new timezone data to your JDKs. Now, you can use the same TZUpdater version and simply use the new “-l” feature to get timezone updates directly from IANA or ICANN as soon as they release them.

This document gives an example on how to use the “-l” option.

There will, of course, be updates to TZUpdater for bug fixes and improvements of the tool itself, and so you should always use the latest release of the tool to take advantage of those improvements.

There are two ways of updating your JDK installations with new timezone information:

  • Directly from IANA, if the machine can reach it
  • From a file obtained from IANA, if the machine does not have direct internet access

2 Procedure for Direct Access to IANA

At the time of this writing, tzdata2024a has just been released by ICANN/IANA. The command to update via the internet is:

# java -jar tzupdater.jar -l https://www.iana.org/time-zones/repository/releases/tzdata2024a.tar.gz

Most companies use proxies in order to access the internet. In that case, you must use some -http(s) options. For example:

java -Dhttp.proxyHost=<HOSTNAME> -Dhttp.proxyPort=<port> -Dhttps.proxyHost=<HOSTNAME>
    -Dhttps.proxyPort=<PORT> -jar tzupdater.jar -l https://www.iana.org/time-zones/repository/releases/tzdata2024a.tar.gz

If your environment uses proxies and you don’t use these options, you will see this error:

"Network issue while connecting to http resource. Please reference tzupdater README"

You must have permissions to write to the /jre/lib directory. If you don’t have write permissions you will see this error:

"Failed: java.nio.file.AccessDeniedException: <JAVA_HOME>/jre/lib/tzdb.dat.dynamic
    java.nio.file.AccessDeniedException: <JAVA_HOME>/jre/lib/tzdb.dat.dynamic
    . . ."

Example (Linux or Solaris):

# java -Dhttps.proxyHost= -Dhttps.proxyPort= -jar tzupdater.jar -v -l https://www.iana.org/time-zones/repository/releases/tzdata2024a.targz
    java.home: <JAVA_HOME>/jre
    java.vendor: Oracle Corporation
    java.version: 1.8.0_351
    Downloaded file to <PATH>/tzdata.tar.gz
    JRE tzdata version: tzdata2022f
    tzupdater tool would update with tzdata version: <version or N/A>  <--------ignore
    Downloaded file to <PATH>/sha512hash
    Renaming <JAVA_HOME>/jre/lib/tzdb.dat to <JAVA_HOME>/jre/lib/tzdb.dat.tzdata2022f
    Renaming <JAVA_HOME>/jre/lib/tzdb.dat.dynamic to <JAVA_HOME>/jre/lib/tzdb.dat
    Validating for : tzdata2024a
    Validation complete
    JRE updated to version : tzdata2024a

3 File Update Method

  1. Go to the TZ Announce mailing list archive and select the most recent “Thread” link.
  2. Click the link to the latest message.
  3. Under the heading “The files are also available via HTTP as follows:” copy the line “https://www.iana.org/time-zones/repository/releases/tzdata2024a.tar.gz”. Make sure that you are getting “tzdata” and not “tzcode”.
  4. Paste that line in the URL frame of a web browser and press Enter or Return.
  5. A pop-up window appears. Choose to save the file to a folder or directory on your machine.
  6. In the same directory where you just copied the tzdata2024a.tar.gz file, create a new file named “tzdata2024a.tar.gz.sha512”
  7. From the TZ Announce mailing list web page, copy and paste the SHA-512 checksum for the file tzdata2024a.tar.gz

To find the the SHA-512 checksum, look under the heading “Here are the SHA-512 checksums for the release files:” copy lines containing the checksum and filename: 7f79394295e00e3a24ebdbf9af3bc454a65f432a93b517e7e96c7f9db9949f6f5fdae9892a9d3789ff44ae0eb1bfe4744d36976b4624659af951d26414f94e65 tzdata2022g.tar.gz
and paste it on one line in the file that you just created “tzdata2022g.tar.gz.sha512”.

When you are finished, you should have a directory which has two entries:

% ls
    tzdata2024a.tar.gz
    tzdata2024a.tar.gz.sha512

Example (Linux or Solaris):

You will need three pieces to update the Java tz database:

  • The latest version of the TZUpdater tool, which you can download from Oracle’s Java download site
  • The tzdata.tar.gz and checksum files from ICANN or IANA.
  • Java SE version 7.0 or higher.

Let’s say that you created a temporary directory. In this directory you have the two icann.org files tzdata2024a.tar.gz and tzdata2024a.tar.gz.sha512. If you unpacked the tzupdater-2_0_0-2015a.zip file in the temporary directory, this directory will look like:

<PATH>/tzupdater.jar

You can update JDK or JRE 7 or higher version installations. You can check by running the java -version command. If not, you can set your PATH environment variable to point to point to the correct version.

To run the updater:

  1. Change your directory to where you have unpacked the tzupdater.jar file:
cd <TEMPORARY_DIR>
  1. Run the updater:
java -jar tzupdater.jar -l file://<PATH>/tzdata2022g.tar.gz
    % su
    Password:
    # java -jar tzupdater.jar -v -l file://<PATH>/tzdata2022g.tar.gz
    java.home: <JAVA_HOME>/jre
    java.vendor: Oracle Corporation
    java.version: 1.8.0_351
    Downloaded file to <PATH>/tzdata.tar.gz
    JRE tzdata version: tzdata2022f
    tzupdater tool would update with tzdata version: <version or N/A>  <--------Ignore
    Downloaded file to <PATH>/sha512hash
    Renaming <JAVA_HOME>/jre/lib/tzdb.dat to <JAVA_HOME>/jre/lib/tzdb.dat.tzdata2022f
    Renaming <JAVA_HOME>/jre/lib/tzdb.dat.dynamic to <JAVA_HOME>/jre/lib/tzdb.dat
    Validating for : tzdata2024a
    Validation complete
    JRE updated to version : tzdata2024a <---------------------------------Verifies the updated version

To test, run tzupdater.jar with the -V option:

% java -jar tzupdater.jar -V
   tzupdater version 2.0.0-b03
   JRE tzdata version: tzdata2024a
   tzupdater tool would update with tzdata version: tzdata2015a  <-------****  Ignore this line.

Do not use the -t option to verify. This will incorrectly report that the update failed. A bug report has been filed in order to clean up the output from these options.

  1. Alternatively, you can calculate a checksum on a Linux machine, using the built-in sha512sum command. You would run it on the tzdata2024a.tar.gz file that you downloaded from the ICANN / IANA site.

3.1 Copy the latest IANA timezone information to the machine that needs updating using the file that you downloaded from the ICANN / IANA site: tzdata2024a.tar.gz

3.2 Calculate the sha512 checksum for the tzdata file and place it in a file name <TZDATA_FILE_NAME>.sha512. The .sha512 file must have only the line with the checksum in hexadecimal:

# /usr/bin/sha512sum tzdata2015c.tar.gz
    28744a8436a2562060252122f8e0e4ab1edcd753bd82a846eda6f0ca74cde3d71efeb5868e637669cfd0a28d1bae02e871fc45c088eb164673c488a5345a22eb  tzdata2024a.tar.gz
    # echo 28744a8436a2562060252122f8e0e4ab1edcd753bd82a846eda6f0ca74cde3d71efeb5868e637669cfd0a28d1bae02e871fc45c088eb164673c488a5345a22eb > tzdata2024a.tar.gz.sha512

Note: On different unix systems there are similar commands which can be used to print the sha512 checksum of tzdata*.tar.gz file.

Linux / Solaris 11:

$ sha512sum tzdata2014b.tar.gz
    8f4884c2576ab91de062ed6277818b220ee43facbe5721f51d33a99fde5b3e299936e94d579662dd813076199efa348d8f26fff1c06b92055b0efba98c0ed226  tzdata2014b.tar.gz

Mac OS:

$ shasum -a 512 tzdata2014b.tar.gz
    8f4884c2576ab91de062ed6277818b220ee43facbe5721f51d33a99fde5b3e299936e94d579662dd813076199efa348d8f26fff1c06b92055b0efba98c0ed226  tzdata2014b.tar.gz

Linux / Solaris 11:

digest -a sha512  tzdata2014b.tar.gz
    8f4884c2576ab91de062ed6277818b220ee43facbe5721f51d33a99fde5b3e299936e94d579662dd813076199efa348d8f26fff1c06b92055b0efba98c0ed226

Mac OS / Linux / Solaris 11:

$ openssl dgst -sha512 tzdata2014b.tar.gz
    SHA512(tzdata2014b.tar.gz)= 8f4884c2576ab91de062ed6277818b220ee43facbe5721f51d33a99fde5b3e299936e94d579662dd813076199efa348d8f26fff1c06b92055b0efba98c0ed226

Windows Example:

Be sure that when you create the file with the sha512 hash code in it, tzdata2024a.tar.gz.sha512, that you remove the .txt suffix that Windows will add by default.

<PATH>\tzupdater-2.3.2>"<JAVA_HOME>\bin\java.exe" -jar tzupdater.jar -V
    tzupdater version 2.3.2-02
    JRE tzdata version: tzdata2022f
    tzupdater tool would update with tzdata version: <version or N/A>  <--------ignore
    <PATH>\tzupdater-2.3.2>"<JAVA_HOME>\bin\java.exe" -jar tzupdater.jar -v -l file:"<PATH>\tzdata2024a.tar.gz"
    java.home: <JAVA_HOME>
    java.vendor: Oracle Corporation
    java.version: 1.8.0_351
    Downloaded file to <PATH>\tzdata.tar.gz
    JRE tzdata version: tzdata2022g
    tzupdater tool would update with tzdata version: <version or N/A>   <-------ignore
    Downloaded file to <PATH>\sha512hash
    Renaming <JAVA_HOME>\lib\tzdb.dat to <JAVA_HOME>\lib\tzdb.dat.tzdata2022f
    Renaming <JAVA_HOME>\lib\tzdb.dat.dynamic to <JAVA_HOME>\lib\tzdb.dat
    Validating for : tzdata2024a
    Validation complete
    JRE updated to version : tzdata2024a
    <PATH>\tzupdater-2.3.2>"<JAVA_HOME>\bin\java.exe" -jar tzupdater.jar -V
    tzupdater version 2.3.2-b02
    JRE tzdata version: tzdata2022g
    tzupdater tool would update with tzdata version: <version or N/A>  <------ignore

The name of the tzdata file will change each time a new update is released from ICANN / IANA. For this most recent update, which contains a Daylight Savings Time change for Egypt, the file name is tzdata2024a.tar.gz. The next release from ICANN / IANA will be named tzdata2024b.tar.gz.


4 References

Oracle Timezone Updater Tool

You can visit these two sites to see if the most recent release has been made available:


Last reviewed on Sat Feb 01 2025 00:00:00 GMT+0000 (Coordinated Universal Time)