Limits of Docker container time zone configuration across base images

Question

Docker Engine does not offer a daemon-level default time zone for containers, leaving each container's local time dependent on image contents, environment variables, and bind mounts. Setting TZ via docker run -e is the documented way to configure a named zone, but its behavior is bounded by the image's userspace libraries and time zone database. In glibc-based images, TZ=America/New_York typically produces correct local time and DST rules when tzdata is present. Alpine-based images frequently omit tzdata, which can cause date to fall back to UTC or fail to resolve named zones entirely.

Because container date conversion libraries such as Python zoneinfo and Java ZoneId read the container's /etc/localtime and TZ rather than the Docker host's system clock directly, the absence of tzdata creates a boundary where the environment variable appears set but does not yield the expected zone abbreviation or offset. Bind-mounting the host /etc/localtime offers an alternative, yet that path may be absent or a symlink on some hosts, introducing another dependency.

Given that Docker Engine provides no built-in time zone inheritance, what are the precise behavioral limits of TZ versus a bind-mounted /etc/localtime when tzdata is missing, and how can teams predict whether a specific base image will honor a named zone without executing the container?

Tasadduq Burney · Answer

Answer to the Core Question Docker’s TZ environment variable only takes effect if the container’s userspace has a time‑zone database that can resolve the zone name. If the base image lacks tzdata (common in Alpine‑based images), the variable is silently ignored and the container falls back to UTC or the system clock. Binding /etc/localtime from the host bypasses the need for tzdata, but it only works when the host path exists, is not a symlink, and the file contains a valid binary time‑zone file. In that case the container reads the binary directly, but no zone abbreviation or DST logic is supplied by name – the binary is already in the correct offset. Why the Difference Matters tzdata present, TZ set – date, Python zoneinfo, Java ZoneId, and most libc functions use the zone name to compute offsets and DST transitions. tzdata missing, TZ set – the variable is parsed but no mapping exists; tools fall back to UTC or report an error. tzdata missing, /etc/localtime bind‑mounted – the binary file is read, giving the correct offset for the current instant, but no named‑zone lookup is possible for future DST changes. Predicting Behaviour Without Running the Container Inspect the image’s package list to see if tzdata is installed. docker run --rm sh -c "apk info tzdata 2>/dev/null || dpkg -l tzdata 2>/dev/null || rpm -q tzdata 2>/dev/null" Check the image’s /usr/share/zoneinfo directory. docker run --rm ls /usr/share/zoneinfo | head Verify the host’s /etc/localtime before mounting. ls -l /etc/localtime && file /etc/localtime Look for a timezone file or symlink that points to a valid zone. readlink -f /etc/localtime When to Use Which Approach If the image already contains tzdata, set TZ=America/New_York. If the image is slim and lacks tzdata, either install it in a derived image or bind‑mount the host /etc/localtime. For deterministic builds that must run in the same zone regardless of host, prefer installing tzdata and setting TZ. Missing Diagnostic Detail To fine‑tune the recommendation, could you confirm whether the base image you plan to use ships with the tzdata package installed?

Limits of Docker container time zone configuration across base images

1 answer

Answer to the Core Question

Why the Difference Matters

Predicting Behaviour Without Running the Container

When to Use Which Approach

Missing Diagnostic Detail

Your perspective belongs here.

0 question comments