Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 64 ยท Time Series

Time Zones

Learn pandas time zones step by step. Localize naive timestamps, convert between zones, handle daylight saving gaps and store everything in UTC.

Time zones are where otherwise correct date code goes quietly wrong. A "daily total" differs depending on whose midnight you use, a meeting scheduled for 9:00 moves by an hour when clocks change, and two columns that look equal on screen turn out to be different instants. pandas handles all of this properly, but only if you tell it which zone each timestamp lives in.

This lesson builds on Dates and Times and Time Series Basics. You will learn the difference between naive and aware timestamps, the two methods that matter (tz_localize and tz_convert), how to survive daylight saving transitions, and a simple storage rule that avoids most trouble.

Naive versus aware

A naive timestamp has no zone: 2026-06-15 09:00 could mean 9 a.m. anywhere. An aware timestamp carries a zone (or a fixed offset) and therefore identifies one exact instant on the global timeline. Everything parsed from plain text such as "2026-06-15 09:00" starts out naive.

Two methods move between these states, and mixing them up is the number one mistake:

  • tz_localize(zone) attaches a zone to naive timestamps. The wall-clock numbers stay the same; it states "these clock readings were taken in New York". It is only allowed on naive data.
  • tz_convert(zone) translates aware timestamps into another zone. The instant stays the same; only the wall-clock display changes. It is only allowed on aware data.
flowchart LR
    N["naive<br/>09:00"] -- "tz_localize('America/New_York')" --> A["aware<br/>09:00-04:00 New York"]
    A -- "tz_convert('UTC')" --> U["aware<br/>13:00+00:00 UTC"]
    U -- "tz_convert('Asia/Tokyo')" --> T["aware<br/>22:00+09:00 Tokyo"]
    A -- "tz_localize(None)" --> N

Localize attaches a zone to clock readings. Convert re-expresses the same instant. Localizing to None throws the zone away again.

Python Localize, convert, compare

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 input()), it gets the next line from this box.

The -04:00 in the output is New York's summer offset (daylight saving time). The dtype reads datetime64[us, America/New_York]: the part in brackets is the unit of resolution (here microseconds; pandas 3 may pick other units depending on how the data was created) followed by the zone. Subtracting naive from aware raises a TypeError, which is a feature: pandas refuses to guess.

Use IANA zone names such as "America/New_York", "Europe/London" or "Asia/Tokyo", not abbreviations like "EST" or "CST", which are ambiguous (CST is used in the US, China and Cuba). IANA names carry the full daylight saving history. pandas reads this database from the tzdata package that it depends on. On a normal computer it is installed with pandas. The Python in your browser has no time zone database, so the examples on this page first run await micropip.install("tzdata"); you would not need that line in your own projects. Fixed offsets such as "UTC" or "+05:30" are fine when you really have only an offset.

Daylight saving transitions

Twice a year, clocks in many regions jump. This creates two kinds of troublesome wall-clock times:

  • Nonexistent times, in spring, when the clock skips forward. In New York on 2026-03-08 the clock goes from 01:59 straight to 03:00, so 02:30 never happens.
  • Ambiguous times, in autumn, when the clock goes back. On 2026-11-01 the hour from 01:00 to 01:59 happens twice, so 01:30 could mean two different instants.

When you tz_localize such values, pandas raises an error by default instead of silently picking one. Two keyword arguments let you decide: nonexistent= and ambiguous=.

Python Gaps and repeated hours

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 input()), it gets the next line from this box.

The options:

Argument Value Effect
nonexistent "shift_forward" / "shift_backward" move to the nearest valid time after / before the gap
nonexistent "NaT" turn the impossible time into a missing value
nonexistent Timedelta shift by a fixed amount
ambiguous boolean array True for the first occurrence (daylight time), False for the second
ambiguous "NaT" mark ambiguous times as missing
ambiguous "infer" guess from the order of values (needs a sorted, hourly-dense series)

Prefer fixing the problem at its source: if you control the data collection, record UTC or an offset so that no ambiguity can arise.

Calendar days versus 24 hours

Daylight saving also changes the meaning of "one day later". A day on the calendar can be 23 or 25 hours long, and pandas gives you both versions on purpose:

Python One day is not always 24 hours

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 input()), it gets the next line from this box.

Adding a Timedelta moves along the global timeline: 12:00 on March 7 plus 24 hours is 13:00 on March 8, because an hour was skipped. DateOffset(days=1) keeps the clock reading at noon. Use Timedelta for durations and DateOffset for calendar logic such as "same time tomorrow". date_range with a daily frequency also follows the calendar, which is why the first range holds three noons.

Store UTC, display local

The most robust rule for real data: store and compute in UTC, convert to local time only when you display or group by local days. UTC has no daylight saving, so arithmetic, sorting and joins are always correct. The next example receives order times as local clock readings from four cities, turns them into one UTC column and then shows two different "day" views.

Python A clean UTC column

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 input()), it gets the next line from this box.

Notice that all four orders fall on January 11 in UTC, yet from Los Angeles's point of view two of them happened on January 10. Neither is wrong; they answer different questions. State the zone whenever you report daily or monthly numbers, and use tz_convert before resample("D") or dt.date when the business day is local.

A few more practical rules:

  • A column holding a single zone is one aware dtype and fast. Text with mixed offsets ("2026-01-01 10:00+01:00" next to "+05:30") makes pd.to_datetime raise a ValueError in pandas 3 until you pass utc=True, which converts everything to UTC at parse time. Do this for logs and API data.
  • tz_localize(None) removes the zone and keeps the local clock reading; tz_convert(None) converts to UTC first, then removes the zone. Pick the second when you need naive UTC timestamps.
  • Time zones work on the index as well: df.tz_localize(...) and df.tz_convert(...) act on a DatetimeIndex. For a column use the .dt accessor.
  • resample and rolling on aware data respect daylight saving: a daily resample in New York produces 23-hour and 25-hour bins on the transition days.

Never call tz_localize on timestamps that are already in UTC just to "add the zone back" and then tz_localize again for the real one. If your data are UTC, localize them to "UTC" once and then tz_convert to the zone you want. Localizing UTC readings directly to "America/New_York" would reinterpret them as New York clock times and shift every value by four or five hours.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You parsed naive timestamps recorded in Paris. Which call correctly marks them as Paris time?

    tz_localize attaches a zone to naive clock readings. tz_convert only works on data that already has a zone, and shifting by a Timedelta changes the instant.
  2. 2. What does tz_convert('Asia/Tokyo') change on an aware series?

    Converting re-expresses the same instant in another zone, so 13:00 UTC becomes 22:00+09:00. Subtracting the two versions gives a zero difference.
  3. 3. On the autumn daylight saving change, tz_localize raises an error for 01:30. Why?

    When clocks go back, the hour from 01:00 to 01:59 repeats. Use ambiguous=... to say which occurrence you mean, or NaT to mark them missing.
  4. 4. What is the safest way to store timestamps for data collected in many regions?

    UTC has no daylight saving, so sorting, arithmetic and joins are always correct. Convert to a local zone when you present results.

Summary

  • Naive timestamps have no zone; aware timestamps pin an exact instant. Subtracting one from the other raises TypeError.
  • tz_localize attaches a zone to naive clock readings; tz_convert re-expresses aware timestamps in another zone. For columns, use the .dt accessor.
  • Use IANA names like "America/New_York", not abbreviations.
  • Daylight saving creates nonexistent and ambiguous local times; control them with nonexistent= and ambiguous=.
  • Timedelta adds elapsed time; DateOffset(days=1) adds a calendar day, and the two differ on transition days.
  • Store UTC, convert to local zones to display or to define local days, and pass utc=True to to_datetime for mixed offsets.

Next: Descriptive Statistics moves from time to numbers, and shows how to summarize a column or a whole table in a few calls.