Complete Guide to Setting Docker Container Timezone to UTC+8 (Asia/Shanghai)

In daily containerized deployments, Docker containers use UTC (Coordinated Universal Time) as the default standard time. For developers in other timezones, this often results in an 8-hour discrepancy in log times and database records. Using a Python Gunicorn application as an example, this article explains in detail how to change a Docker container's timezone to UTC+8 (Asia/Shanghai). ## Method 1: Mount the Host's Timezone File (Quickest) If you prefer not to modify the Docker image, the simplest and most recommended method is to mount the host machine's timezone file directly in the `docker run` command. ```bash docker run -d \ --name fcp-archive-web-lib00 \ --restart unless-stopped \ -p 18080:18080 \ -v /etc/localtime:/etc/localtime:ro \ fcp-archive-web:1.0 \ gunicorn --bind 0.0.0.0:18080 wsgi:app ``` **How it works**: Linux systems typically read `/etc/localtime` to determine the timezone. By using `-v /etc/localtime:/etc/localtime:ro` (`ro` stands for read-only), the container automatically syncs with the host's timezone settings. This is currently the most compatible OS-level modification method. --- ## Method 2: Use Environment Variables (Conditional) You might often see the `-e TZ=Asia/Shanghai` approach. However, **this is not guaranteed to work 100% of the time**. Whether this environment variable takes effect depends on whether the base image (e.g., `alpine`, `debian`) has `tzdata` (timezone database) installed. If the image is too minimal and lacks this component, or if the application (like statically compiled Go binaries) hardcodes timezone logic, the environment variable will be ignored. --- ## Method 3: Configure in Dockerfile (Best Practice) To ensure **high portability** of the image (meaning the time is correct regardless of which host it's deployed on), the best practice is to explicitly install `tzdata` and configure the timezone within the `Dockerfile`. Taking `python:3.11-slim` as an example, since it is Debian-based and includes `tzdata` package sources, we can optimize it like this: ```dockerfile # Base image FROM python:3.11-slim # Maintainer info LABEL maintainer="DP@lib00" # Install tzdata to ensure the timezone database is complete, and set system timezone RUN apt-get update && apt-get install -y tzdata && \ ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \ echo "Asia/Shanghai" > /etc/timezone && \ rm -rf /var/lib/apt/lists/* # Set environment variable ENV TZ=Asia/Shanghai # Set working directory for wiki.lib00.com project WORKDIR /app COPY requirements.txt /app/requirements.txt RUN pip install --no-cache-dir -r /app/requirements.txt COPY . /app CMD ["gunicorn", "--bind", "0.0.0.0:18080", "wsgi:app"] ``` This approach removes the dependency on the host machine's configuration and avoids potential configuration conflicts. --- ## Pitfall Warning: Timezone Issues at the Python Code Level Even if the system-level timezone configuration is perfectly correct, incorrect function calls at the code level will still result in wrong times. Be sure to check your Python business logic: * ✅ **Correct usage**: `datetime.datetime.now()`. This reads the current system timezone (UTC+8). * ❌ **Incorrect usage**: `datetime.datetime.utcnow()`. **No matter how you configure the system timezone, this will ALWAYS return UTC time**. If your business logic requires it, replace it with `datetime.datetime.now(datetime.timezone.utc)` or simply use `now()`.