Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 64 ยท Data Types

Dates and Times

Parse text with to_datetime, use the .dt accessor, do date arithmetic with Timedelta, build ranges with date_range, and understand periods and time zones.

Dates are the most common source of silent bugs in data work. A column that looks like dates is usually just text: "03/04/2024" could be the third of April or the fourth of March, and sorting the text puts "10/01" before "2/01". Once you convert a column to a real datetime dtype, pandas can sort it, subtract it, group it by month and plot it correctly.

This lesson covers the building blocks: parsing with to_datetime, reading pieces with the .dt accessor, doing arithmetic with Timedelta, generating sequences with date_range, and how periods and time zones fit in. The next chapters on Time Series Basics and Resampling build on everything here.

Parsing text with to_datetime

pd.to_datetime turns strings (or numbers) into datetimes. Give it a format whenever you know the layout; it is faster, and it removes any guesswork about day versus month.

Python Parsing dates with an explicit format

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.

Common format codes: %Y four-digit year, %m month number, %d day, %H:%M:%S time, %b short month name (Mar), %B full month name. A slash date like 01/02/2024 is ambiguous, so state the order with format= or dayfirst=True.

Bad values and the errors argument

By default a value that cannot be parsed raises an error. With errors="coerce" it becomes NaT ("not a time"), the datetime version of NaN, so you can inspect the failures just like with to_numeric in Data Types and Conversion.

Python NaT for unparseable dates

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.

2024-02-30 fails because February has no 30th. As always: coerce, then look at what failed.

In pandas 3, the resolution of a parsed datetime follows the input. Strings usually give datetime64[us] (microseconds), where older versions always used nanoseconds. You rarely need to care, but a dtype print may look different from older tutorials, and dates outside the nanosecond range (before 1678 or after 2262) now parse fine.

The Timestamp object

One date and time is a pd.Timestamp. It has the same attributes the .dt accessor offers for whole columns.

Python A single Timestamp

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.

A Timestamp is pandas' counterpart to Python's datetime.datetime; see Dates and Times in Python for the standard-library version.

The .dt accessor

Just as .str gives text methods, .dt gives datetime methods on a column of dates. It exists only on datetime columns, so convert first.

Python Extracting parts of a date 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.

Useful members of .dt:

Member Result
year, month, day, hour, minute integer parts
dayofweek, day_name(), month_name() weekday number (Monday = 0) or names
dayofyear, quarter, isocalendar() position in the year; ISO year/week/day
is_month_end, is_quarter_start, is_leap_year boolean flags
floor("D"), ceil("h"), round("15min"), normalize() snap to a unit
strftime(fmt) format as text
to_period("M") convert to a period

Extracting year/month columns is the usual first step before grouping; groupby Basics shows how to use them.

Formatting and parsing: isoformat, strftime and strptime

Three small tools convert between a Timestamp and text. isoformat() writes the unambiguous ISO 8601 form (2025-03-09T14:30:15.250000+00:00), which is what APIs and databases expect; sep= changes the T, and timespec="seconds" trims the fraction. strftime(format) writes any layout you describe with % codes (%d/%m/%Y). The reverse, reading text with a known layout, is pd.to_datetime(text, format=...) or the standard library's datetime.strptime(text, format). Prefer to_datetime on whole columns, because it is vectorised; strptime handles one string at a time.

Other handy pieces: .date() and .time() split a timestamp into plain Python date and time objects, .timestamp() gives seconds since 1970-01-01 UTC, and .replace(hour=0, ...) changes single fields (for midnight, .normalize() is shorter). pd.date_range also accepts end with periods to count backwards, or start, end and periods to spread points evenly, and DateOffset objects such as DateOffset(months=1, days=2) or BDay(2) move a date by calendar or business steps.

Python isoformat, strftime and strptime

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 last line shows why offsets exist: adding two ordinary days to a Friday lands on Sunday, while BDay(2) skips the weekend and lands on Tuesday.

Date arithmetic with Timedelta

Subtracting two datetimes gives a Timedelta, a length of time. Adding a Timedelta to a datetime moves it forward.

Python Differences and offsets

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.

A Timedelta is a fixed length (days, hours, seconds). pd.DateOffset is calendar-aware: adding one month to January 31 lands on the last day of February, whereas adding 30 days lands in March. Use offsets when you mean "the same day next month".

Note that Timedelta has .days but not "months" or "years", since those have no fixed size. To count whole months between dates, compare their to_period("M") values instead.

Creating sequences with date_range

pd.date_range generates regularly spaced timestamps. Give it two of start, end and periods, plus a frequency string.

Python date_range frequencies

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.

Frequency strings you will use: "D" calendar day, "B" business day, "h" hour, "min" minute, "W" week, "MS" month start, "ME" month end, "QS" quarter start, "YS" year start. (The older "M" and "H" spellings were removed in pandas 3.)

Timestamps versus periods

A Timestamp is an instant. A Period is a whole span such as "March 2024" or "the 2024 fiscal year". Periods suit monthly or quarterly reporting, because you cannot mix up the first or last moment of the month.

flowchart LR
    A["Timestamp<br/>2024-03-15 14:30"] -- "to_period('M')" --> B["Period<br/>2024-03"]
    B -- "start_time / end_time" --> C["2024-03-01 00:00<br/>to 2024-03-31 23:59:59"]
    B -- "+ 1" --> D["Period 2024-04"]

A Period names a span; converting back gives its first and last instant, and adding 1 moves to the next span.

Python Periods

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.

Time zones overview

A datetime is naive when it has no time zone and aware when it does. Naive values are fine inside one location; use aware values (best stored in UTC) when data crosses regions. The key methods are tz_localize (attach a zone to naive values) and tz_convert (change an aware value to another zone). The dedicated lesson Time Zones covers daylight saving traps. Named zones need time-zone data that may not be loaded in the browser, so only UTC runs live here:

Python Naive versus aware (UTC)

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.

On a normal installation you would convert with aware.dt.tz_convert("Asia/Tokyo"), which shifts the clock time by the zone offset while keeping the same instant.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you pass format='%d/%m/%Y' to pd.to_datetime for the text '01/02/2024' when day comes first?

    Slash dates are ambiguous. pandas guesses month-first unless you say otherwise, so state the layout (or use dayfirst=True).
  2. 2. What does errors='coerce' do in pd.to_datetime?

    coerce replaces values that cannot be parsed with NaT so you can find and inspect them afterwards.
  3. 3. What is the difference between pd.Timedelta(days=30) and pd.DateOffset(months=1)?

    30 days is always 30 days. One month is a calendar step: Jan 31 plus one month is Feb 29 in 2024, not a date in March.
  4. 4. Which accessor gives you the weekday name of every value in a datetime column?

    Datetime columns have the .dt accessor, and day_name() returns names like 'Friday'. The .str accessor is for text.

Summary

  • Convert text with pd.to_datetime; give a format for ambiguous layouts and errors="coerce" to turn bad values into NaT.
  • .dt exposes parts (year, month, day_name()), flags (is_month_end) and rounding (floor, normalize).
  • Subtracting datetimes gives a Timedelta; use DateOffset for calendar steps like "next month".
  • date_range builds regular sequences from a start, end or number of periods and a frequency such as "D", "B", "MS" or "ME".
  • A Period names a span (a month); a Timestamp is an instant.
  • Naive datetimes have no zone; aware ones do. Store aware values in UTC.

Next: Categorical Data.