Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท CLI Flags

Node.js TZ environment variable

Reference for the TZ environment variable in Node.js: how it sets the local time zone for Date and Intl, changing it at runtime, and why servers should run in UTC.

JavaScript's Date has two views of an instant: UTC, and "local time", which depends on the machine's time zone. Node.js takes that zone from the TZ environment variable when it is set, and from the operating system otherwise. Methods such as toString(), getHours(), getTimezoneOffset() and Intl.DateTimeFormat without an explicit timeZone all follow it.

Node is unusual among runtimes in that you may also change process.env.TZ while the program runs. The change takes effect right away for new date calculations.

NODE
// shell: TZ=Europe/Berlin node app.js      (Windows cmd: set TZ=...)

Try it

Node.js TZ changes local time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Switching zones while running

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
// TZ=<IANA name | POSIX rule>        e.g. UTC, Europe/Paris, America/Chicago
// process.env.TZ = 'Asia/Tokyo';     // runtime change
// Intl.DateTimeFormat().resolvedOptions().timeZone: string
Value Meaning
UTC Local time equals UTC, no daylight saving.
Area/City An IANA time zone with its rules, for example America/New_York.
unset Use the operating system's zone.

Edge cases: an invalid name does not throw; local time silently behaves as UTC (offset 0). Windows needs IANA names for Node to understand them, which works in current releases; older shells may show Windows zone names.

Usage notes

  • Run servers in UTC. Store and compute timestamps as instants (Date.now(), ISO strings with Z), and convert to a user's zone only for display with Intl.DateTimeFormat and its timeZone option. This avoids daylight-saving bugs and machines that disagree.
  • Containers often have no zone database for the OS but Node carries ICU data, so TZ=Europe/Paris still works in a minimal image.
  • Setting it at runtime is handy in tests so date formatting does not depend on the developer's machine. Set it before creating the dates you assert on, and restore it afterwards. With node:test you can run the whole file under a fixed zone by starting it with TZ set.
  • Test runner and child processes inherit the variable; a value changed in code is also inherited by processes spawned afterwards.
  • ISO output is zone-free. toISOString() and getTime() ignore it. toString(), toLocaleString() and the get* hour/day methods do not.
  • Daylight saving makes some local times missing or repeated, so constructing dates from local fields (new Date(2025, 2, 30, 2, 30)) can shift by an hour in some zones.
  • Do not store local times without the offset. 2025-03-09T02:30 alone is ambiguous.
  • Explicit beats ambient: Intl.DateTimeFormat with timeZone and Temporal-style libraries make the zone part of the code instead of the environment.