Python のタイムゾーン処理 - zoneinfo と pytz の使い分け

naive と aware - 最初に押さえるべき二分法

Python の datetime オブジェクトは、タイムゾーン情報を持たない naive と、tzinfo 属性に情報を持つ aware の 2 種類に分かれます。datetime.now() の戻り値はデフォルトで naive であり、これを単純に文字列化したり比較したりすると、サーバーのタイムゾーンに依存する暗黙の挙動が混入します。本番環境では UTC で動いていても、開発環境が JST だと意図せず時差 9 時間のずれが発生する典型例です。

実務での原則は明快で、入力された日時は可能な限り早く aware に変換し、内部処理は常に aware で行い、表示や永続化の直前まで文字列化しないことです。aware と naive を混在させて比較や減算を行うと TypeError が発生するため、型チェッカー (mypy や pyright) で datetime と aware datetime を区別する型エイリアスを定義しておくと防御策になります。

zoneinfo モジュール - Python 3.9 の標準解

Python 3.9 で PEP 615 として導入された zoneinfo モジュールは、IANA タイムゾーンデータベースを直接利用する標準実装です。zoneinfo.ZoneInfo("Asia/Tokyo") のように IANA 名で取得し、datetime に渡すだけで aware オブジェクトが手に入ります。第三者ライブラリへの依存が消え、ロケールに依存しない確定的な動作が保証されるのが最大の利点です。

ただし zoneinfo は、デフォルトで OS が提供する tzdata を参照する設計です。Linux や macOS では /usr/share/zoneinfo にデータが揃っているため問題ありませんが、Windows には標準で IANA tzdata がありません。この場合 pip install tzdata で補助パッケージを入れる必要があり、Docker イメージで Alpine Linux など最小構成の OS を使う際にも明示的なインストールが求められます。

pytz - 長年使われてきた選択肢

pytz は 2003 年から続くサードパーティライブラリで、Python 3.9 以前は IANA タイムゾーンを扱うほぼ唯一の選択肢でした。pytz には独特の API があり、tz.localize(naive_dt) で aware に変換する必要があります。datetime コンストラクタに tzinfo として直接渡すと、歴史的な LMT (地方平均時) の値で初期化されてしまい、東京の場合 9 時間 19 分のずれが発生する有名な罠があります。

pytz から zoneinfo へ移行する場合、最も注意すべきは API の差異です。pytz の tz.normalize() は zoneinfo に存在しません。zoneinfo は datetime の標準的な算術演算で正しい結果を返すよう設計されているため、normalize 相当の処理が不要になります。既存コードで normalize を呼んでいる箇所は、zoneinfo に置き換える際に削除して問題ありません。

fold 属性 - サマータイムの曖昧さを解決

Python 3.6 で datetime に追加された fold 属性は、サマータイム終了時に発生する「同じ時刻が 2 回登場する」問題を解決します。例えば米国東部時間で 2026 年 11 月 1 日午前 1 時 30 分は EDT と EST の両方で存在し、どちらの時刻なのかを区別する必要があります。fold=0 が最初の出現 (EDT、UTC-4)、fold=1 が 2 度目の出現 (EST、UTC-5) を意味します。

サマータイム開始時の「存在しない時刻」 (例: 春の 2:00 から 3:00 にスキップする際の 2:30) は、fold ではカバーされず、zoneinfo は内部的にその時刻を直前の時刻として扱います。アラーム機能やジョブスケジューラーを実装する場合、fold とこの存在しない時刻の両方を考慮した境界値テストが不可欠です。サマータイム廃止地域でも、過去の歴史的なタイムスタンプを扱うコードでは同じ問題が起きえます。

tzdata の更新 - 鮮度を保つ運用

IANA tzdata は年に 5〜10 回更新され、各国のサマータイム廃止や標準時変更を反映します。2026 年に入ってからもエジプトやヨルダンでサマータイム制度の変更が議論されており、最新の tzdata を反映しない環境では未来の時刻計算が誤った結果を返します。コンテナ運用では、ベースイメージ更新のサイクルが tzdata の鮮度に直結するため、四半期に 1 度はベースイメージを再ビルドする運用が望ましいでしょう。

Lambda や Cloud Run など完全マネージド環境では、ランタイムに同梱される tzdata のバージョンを確認できません。重要なジョブで未来日付のタイムゾーン計算を行う場合は、pip でインストールした tzdata パッケージの方を明示的に優先するよう ZoneInfo.clear_cache() と TZPATH 環境変数で制御する設計にすると、依存関係を完全にコントロールできます。

実務でのベストプラクティス

Python 3.9 以降を使えるプロジェクトでは、新規コードは zoneinfo を選ぶのが基本方針です。既存コードに pytz が混在している場合、機能境界 (例: API 入出力) ごとに段階的に移行すると安全に置き換えられます。型ヒント上は zoneinfo.ZoneInfo と pytz.BaseTzInfo の両方を tzinfo として扱えるため、内部処理は型を意識せずに混在運用が可能です。

もう一つ重要なのは、内部処理を UTC で統一する設計です。aware datetime であっても、Asia/Tokyo のままで複雑な算術演算を行うとサマータイム境界の挙動に振り回されます。入力時にユーザーのタイムゾーンから UTC に変換し、内部は UTC で計算し、出力時にユーザーのタイムゾーンへ戻す三段階モデルを徹底すれば、ほとんどのバグを根絶できます。データベースの永続化も TIMESTAMP WITH TIME ZONE 型で UTC を保存する形に統一するのが鉄則です。