ZetCode

Pandas Datetimes

last modified November 17, 2026 Python 3.15

Dates and times appear in almost every data set, but they usually arrive as plain strings or numbers. Pandas has a family of types for working with them: a Timestamp represents one moment in time, a Timedelta is a duration, and a DatetimeIndex is an index made of timestamps. This article shows how to create these values and how to get information out of them.

The examples were run with pandas 3.1.1. In this version the printed dtype may appear as datetime64[us]; older releases often show datetime64[ns]. The resolution unit differs, but the dates are the same. For the standard-library approach to dates see the Python datetime tutorial.

Converting strings with to_datetime

The to_datetime function turns strings into timestamps. Given a list of ISO-style dates in year-month-day order, it returns a DatetimeIndex — an index whose entries are timestamps rather than ordinary labels. Pandas recognises this common format automatically.

dt_from_strings.py
import pandas as pd

dates = pd.to_datetime(['2026-01-15', '2026-02-20', '2026-03-25'])
print(dates)

The three strings have become real date values, printed in the same year-month-day form. Because they are dates now, we can sort them, subtract one from another, or extract their parts — operations that would not make sense on plain text.

$ python dt_from_strings.py
DatetimeIndex(['2026-01-15', '2026-02-20', '2026-03-25'],
              dtype='datetime64[us]', freq=None)

Giving an explicit format

When dates use another arrangement, we can describe it with a format string — a pattern of percent codes that tells Pandas where the day, month and year sit. Passing it as format= removes any guesswork and is also faster, because the parser does not have to try several interpretations. Here %d is a two-digit day, %m a two-digit month and %Y a four-digit year.

dt_format.py
import pandas as pd

dates = pd.to_datetime(['15/01/2026', '20/02/2026'], format='%d/%m/%Y')
print(dates)

The input strings put the day first, which could easily be mistaken for a month by an automatic parser. With the explicit format there is no ambiguity: 15/01/2026 is 15 January 2026, and the printed result shows it in the standard year-first order.

$ python dt_format.py
DatetimeIndex(['2026-01-15', '2026-02-20'], dtype='datetime64[us]', freq=None)

Handling bad values with errors='coerce'

Real data often contains a bad entry. By default to_datetime raises an error in that case. Setting errors='coerce' instead turns any value it cannot parse into NaT, which stands for "Not a Time" and is the date equivalent of a missing value. The rest of the values are converted normally.

dt_coerce.py
import pandas as pd

dates = pd.to_datetime(['2026-01-15', 'not a date', '2026-03-25'],
                       errors='coerce')
print(dates)

The middle entry could not be parsed, so it appears as NaT. The first and third entries are unchanged. This behaviour lets a column keep all of its rows even when a few dates are unusable, and missing-date utilities can then detect or fill those cells.

$ python dt_coerce.py
DatetimeIndex(['2026-01-15', 'NaT', '2026-03-25'], dtype='datetime64[us]',
              freq=None)

Timestamp values

A Timestamp is Pandas' single date-and-time value, much like a Python datetime.datetime object but with Pandas features. It can be created directly from a string, and its year, month and day attributes give the individual parts without any parsing.

dt_timestamp.py
import pandas as pd

t = pd.Timestamp('2026-11-17 14:30:00')
print(t)
print(t.year, t.month, t.day)

The first line prints the whole moment, including the time of day; the second prints the three requested components, 2026, 11 and 17, separated by spaces. This is the natural tool when a single date is needed rather than a whole column of them.

$ python dt_timestamp.py
2026-11-17 14:30:00
2026 11 17

Epoch values with unit

Some data stores dates as epoch values: the number of time units elapsed since 1 January 1970, also called the Unix epoch. The unit argument tells Pandas what each number means — 's' for seconds, 'ms' for milliseconds or 'D' for days. Here the values 0, 86400 and 172800 are whole seconds, so they land on the first three days of 1970.

dt_epoch.py
import pandas as pd

dates = pd.to_datetime([0, 86400, 172800], unit='s')
print(dates)

A day has 86400 seconds, so adding that amount advances the date by exactly one day. The three numbers become midnight on 1, 2 and 3 January 1970. Choosing the wrong unit would give completely different dates, so it is worth checking what a data source actually stores.

$ python dt_epoch.py
DatetimeIndex(['1970-01-01', '1970-01-02', '1970-01-03'],
              dtype='datetime64[us]', freq=None)

The .dt accessor

On a Series of dates, the .dt accessor exposes the parts of each value as separate Series. Attributes such as year, month and day return numbers, while the day_name() method returns the weekday as text. An accessor is a namespace of operations available only for a particular kind of data — here, datetime data.

dt_accessor.py
import pandas as pd

df = pd.DataFrame({
    'date': pd.to_datetime(['2026-01-15', '2026-05-20', '2026-12-25'])
})
print(df['date'].dt.year)
print(df['date'].dt.month)
print(df['date'].dt.day)
print(df['date'].dt.day_name())

Each call returns a Series with the same index as the original, so the results can be added straight back into the DataFrame. The weekday names are computed from the actual calendar dates: 15 January 2026 is a Thursday, 20 May 2026 is a Wednesday and 25 December 2026 is a Friday.

$ python dt_accessor.py
0    2026
1    2026
2    2026
Name: date, dtype: int32
0     1
1     5
2    12
Name: date, dtype: int32
0    15
1    20
2    25
Name: date, dtype: int32
0     Thursday
1    Wednesday
2       Friday
Name: date, dtype: str

Arithmetic with Timedelta

A Timedelta is a length of time, such as ten days or one week. Adding or subtracting one from a Timestamp shifts it by that amount, while subtracting two Timestamps produces a Timedelta. The days attribute returns the whole number of days in the resulting duration.

dt_timedelta.py
import pandas as pd

t = pd.Timestamp('2026-01-15')
print(t + pd.Timedelta(days=10))
print(t - pd.Timedelta(weeks=1))
delta = pd.Timestamp('2026-03-01') - pd.Timestamp('2026-01-01')
print(delta)
print(delta.days)

Ten days after 15 January is 25 January, and one week before it is 8 January. The span from 1 January to 1 March 2026 covers 31 days in January and 28 in February, so the difference is 59 days, shown both as a Timedelta and as the integer 59.

$ python dt_timedelta.py
2026-01-25 00:00:00
2026-01-08 00:00:00
59 days 00:00:00
59

Timezone-naive and timezone-aware

A timestamp can be timezone-naive, meaning it carries no information about where in the world it applies, or timezone-aware, meaning a timezone is attached. The tz_localize method attaches a timezone to a naive value, and tz_convert expresses an aware value in another timezone while keeping the same instant. Here we label noon as UTC, then view it in Bratislava.

dt_timezone.py
import pandas as pd

naive = pd.Timestamp('2026-11-17 12:00:00')
aware = naive.tz_localize('UTC')
print(naive)
print(aware)
print(aware.tz_convert('Europe/Bratislava'))

The naive value prints with no offset. After tz_localize('UTC') it carries a +00:00 offset, and after conversion to Europe/Bratislava it becomes 13:00 with a +01:00 offset. The clock reading changed, but it is the same moment in time; 17 November is after the autumn clock change, so Bratislava is one hour ahead of UTC.

$ python dt_timezone.py
2026-11-17 12:00:00
2026-11-17 12:00:00+00:00
2026-11-17 13:00:00+01:00

Source

Pandas to_datetime Documentation, Pandas Timestamp Documentation, Pandas Timedelta Documentation, and Pandas Time Series Documentation

In this article we have converted strings with to_datetime, specified an explicit format, handled invalid dates with errors='coerce', created Timestamp values, converted epoch numbers with unit, extracted parts through the .dt accessor, done arithmetic with Timedelta, and distinguished timezone-naive from timezone-aware values. For working with dates in the standard library see the Python datetime tutorial, and for grouping dates into periods see Pandas resampling.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Pandas tutorials.