Configure timezones in Java

  • Article

You can configure timezones in Java through various methods, enabling applications to operate in the desired timezone context. Two common approaches are setting the TZ environment variable and specifying the JVM property -Duser.timezone. This article provides a brief overview of both methods.

Setting the TZ environment variable

The TZ environment variable is a standard way to set the timezone for applications running on Unix-like operating systems. When you set this variable, the Java Virtual Machine (JVM) picks up the timezone setting during startup.

Set the TZ environment variable at the OS level

Use the following steps to set the TZ environment variable at the operating system level:

  1. Identify the desired timezone. Timezones are typically specified in the "Area/Location" format, such as "America/New_York" or "Europe/London".

  2. Set the TZ environment variable using one of the following methods:

    • On Unix/Linux systems, use the following command to set the variable in the terminal or in your shell configuration file - .bashrc, .bash_profile, .zshrc, and so on:

      export TZ=America/New_York

    • On Windows systems, use the following command to set the variable in the command prompt or through system environment settings:

      set TZ=America/New_York

  3. Restart the application so that the JVM can pick up the new timezone setting.

Example

In the following example, the application myapp.jar runs in the Europe/London timezone:

export TZ=Europe/London
java -jar myapp.jar

Setting the TZ environment variable in a Dockerfile

When you run Java applications in containers, you can set the TZ environment variable within the Dockerfile to ensure that the container runs in the desired timezone.

Dockerfile example

The following example configures the container to use the America/New_York timezone by setting the TZ environment variable and installing the tzdata package:

# Use a base image with Java installed
FROM mcr.microsoft.com/openjdk/jdk:21-mariner

# Set the timezone environment variable
ENV TZ=America/New_York

# Set the working directory
WORKDIR /app

# Copy the application JAR file to the container
COPY myapp.jar /app/myapp.jar

# Run the application
CMD ["java", "-jar", "myapp.jar"]

Setting the JVM property -Duser.timezone

Another method to configure the timezone in Java is to specify the -Duser.timezone property when starting the JVM. This method is platform-independent and enables setting the timezone directly from the command line or within application scripts.

Use the following steps to set the -Duser.timezone property:

  1. Identify the desired timezone. Similar to the TZ environment variable, the timezone is specified in the "Area/Location" format.

  2. Set the -Duser.timezone property by adding it to the Java command line when starting the application, as shown in the following example:

    java -Duser.timezone=America/New_York -jar myapp.jar

Example

In the following example, the application myapp.jar runs in the Asia/Tokyo timezone:

java -Duser.timezone=Asia/Tokyo -jar myapp.jar

Other systems and environments

You can apply the principles of configuring timezones in Java using the TZ environment variable and the -Duser.timezone JVM property to other systems and environments. Whether you run applications on cloud platforms, within virtual machines (VMs), or in various container orchestration systems, you can use the same methods to ensure that your Java applications operate in the correct timezone context.

On cloud platforms, configure the TZ environment variable or JVM property within your deployment scripts or environment configuration settings.

On virtual machines, set the TZ environment variable in your VM's environment or use the JVM property in your application startup scripts.

With container orchestration, use the Dockerfile example for containerized applications, ensuring that the timezone data is available and correctly set.

By following these principles, you can achieve consistent timezone configuration across different deployment environments for your Java applications.