tzlocal：Python 本地时区获取的实用解法

tzlocal 在 GitHub 上拿到了 219 个 Star。

Python 里处理时区一直是个绕不开的问题。标准库的 datetime 和 zoneinfo 功能全面，提供了时区数据库和转换能力，但缺了一个基础功能：获取系统当前的本地时区。代码能拿到当前时间，但不知道你处在哪个时区。

这个问题在 Linux 上尤其突出。不同发行版存放时区配置的方式完全不同。有的用 /etc/timezone 文本文件，有的把时区信息编码进 /etc/localtime 二进制文件，有的写在 /etc/sysconfig/clock 里。还有的靠 /etc/localtime 的符号链接指向时区名称。想写一个通用代码去覆盖所有这些情况，几乎不可能。

tzlocal 就是专门来解决这个问题的。

1、怎么用

核心用法只有一行：

from tzlocal import get_localzone
tz = get_localzone()

返回的 tz 是一个标准 zoneinfo 对象，可以直接用在 datetime 的时区参数里。不需要手动配置，不需要解析系统文件，也不需要你知道时区名称。

拿到 tz 对象之后，你可以用它来创建带时区的时间：

from datetime import datetime
dt = datetime(2025, 4, 10, 7, 22, tzinfo=tz)

也可以在不同时区之间做转换：

from zoneinfo import ZoneInfo
eastern = ZoneInfo("US/Eastern")
dt.astimezone(eastern)

如果只需要时区名称，用 get_localzone_name()：

from tzlocal import get_localzone_name
get_localzone_name()
# "Asia/Shanghai"

注意在 Unix 上，如果系统没有配置时区，get_localzone_name() 会报错，但 get_localzone() 仍然能返回一个有效对象，只不过时区名会显示为 local。

2、支持的范围

Windows 2000 及以后版本，以及任何带 /etc/localtime 或 /usr/local/etc/localtime 的 Unix 类系统，都在支持范围内。Windows 下通过注册表获取时区信息，Unix 下通过分析系统配置文件。如果在你机器上跑不起来，可以直接提 bug。

3、为什么需要这个库

Linux 发行版的时区配置是出了名的混乱。tzlocal 会按顺序检查这些已知的配置文件路径：/etc/timezone、/var/db/zoneinfo、/etc/sysconfig/clock、/etc/conf.d/clock。如果 /etc/localtime 是一个符号链接，它还能从链接路径中提取时区名。

整个流程有清晰的回退逻辑。如果找到了多个配置来源，它会根据优先级做选择。如果完全没有找到任何配置，它也保证能返回一个可用的时区对象，默认回退到 UTC。对于时区配置残缺不全的机器，这个兜底逻辑非常实用。

4、它不适合做什么

这个库不适合用来做当前时间在 UTC 和本地时间之间的简单转换。那种场景用 Python 的 time 模块就够了。tzlocal 的价值在于你需要知道时区名称，或者需要处理过去和未来时间的跨时区转换，这些场景下没有本地时区信息是办不到的。

5、版本变化

3.0 版是一次重要架构调整，不再返回 pytz 对象，改为 Python 3.9 内置的 zoneinfo。4.0 版通过 pytz_deprecation_shim 做了向后兼容，同时增加了更详细的配置错误提示，方便排查问题。5.0 版移除了 shim，完全回归 zoneinfo。需要 pytz 的用户需要停留在 4.x 版本。

6、Docker 的问题

Docker 镜像的时区配置经常不完整，这会导致 tzlocal 报错或者返回错误的时区。如果容器时间不对，最直接的解决办法是在容器启动时设置 TZ 环境变量，指定你需要的时区。

6、出问题了怎么办

如果结果不对，开启调试日志就能看清每一步的排查过程：

import logging
logging.basicConfig(level="DEBUG")
import tzlocal
tzlocal.get_localzone()

输出会列出找到的每个配置文件和路径，以及它们的优先级对比结果。如果你的系统时区配置有问题，这一步基本能定位到原因。

al.get_localzone()

输出会列出找到的每个配置文件和路径，以及它们的优先级对比结果。如果你的系统时区配置有问题，这一步基本能定位到原因。