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.
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.
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.
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.
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.
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.
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.
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.
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
List all Pandas tutorials.