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.
// shell: TZ=Europe/Berlin node app.js (Windows cmd: set TZ=...)
Try it
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.
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
// 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 withZ), and convert to a user's zone only for display withIntl.DateTimeFormatand itstimeZoneoption. 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/Parisstill 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:testyou can run the whole file under a fixed zone by starting it withTZset. - 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()andgetTime()ignore it.toString(),toLocaleString()and theget*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:30alone is ambiguous. - Explicit beats ambient:
Intl.DateTimeFormatwithtimeZoneandTemporal-style libraries make the zone part of the code instead of the environment.