Pandas Date Ranges and Offsets
last modified November 17, 2026 Python 3.15
A DatetimeIndex is an index whose labels are dates and times.
Pandas can build one automatically with date_range, choosing a
start, an end and a step. The step is a frequency: a rule describing
how far apart consecutive labels are, written either as a short alias such as
'D' or as an offset object.
This article shows how to generate ranges, how to move them with
DateOffset and shift, and how to work with
business-day calendars. For individual timestamp values and their components
see the Pandas datetime tutorial; for
splitting time series into periods see Pandas
resampling. All examples were run with pandas 3.1.1, which reports
datetimes at microsecond resolution (datetime64[us]).
Building a range with start and end
Given start and end, date_range
produces daily dates by default, including both endpoints. The result is a
DatetimeIndex whose freq attribute records the rule that was
used, here D for daily.
import pandas as pd
idx = pd.date_range('2026-11-16', '2026-11-20')
print(idx)
Five dates appear, one for each day from 16 to 20 November 2026. Because both strings are dates without times, every label is at midnight.
$ python dr_range.py
DatetimeIndex(['2026-11-16', '2026-11-17', '2026-11-18', '2026-11-19',
'2026-11-20'],
dtype='datetime64[us]', freq='D')
Specifying periods and a frequency
Instead of an end date you may give periods, the number of labels
to generate. Supplying freq='h' then steps by hours rather than
days. Only two of the three arguments start,
end and periods are needed; Pandas infers the rest.
import pandas as pd
idx = pd.date_range('2026-11-16', periods=4, freq='h')
print(idx)
The four labels all fall on 16 November, beginning at 00:00 and advancing by
one hour. The freq line confirms the hourly step.
$ python dr_periods.py
DatetimeIndex(['2026-11-16 00:00:00', '2026-11-16 01:00:00',
'2026-11-16 02:00:00', '2026-11-16 03:00:00'],
dtype='datetime64[us]', freq='h')
Business days with bdate_range
A business day is a weekday, Monday through Friday. The
bdate_range helper generates only those days, skipping Saturdays
and Sundays. It is a shorthand for date_range with a business-day
frequency.
import pandas as pd
idx = pd.bdate_range('2026-11-16', '2026-11-22')
print(idx)
The requested span ends on Sunday 22 November, but the last label is Friday
20 November. The weekend is absent and freq='B' shows why.
$ python dr_bdate.py
DatetimeIndex(['2026-11-16', '2026-11-17', '2026-11-18', '2026-11-19',
'2026-11-20'],
dtype='datetime64[us]', freq='B')
Common frequency aliases
A frequency alias is a short code for a step size. D means a
calendar day, B a business day, h an hour and
ME the end of a month. The last one snaps each label to the
final calendar day of its month, which is useful for monthly reports.
import pandas as pd
print('D: ', list(pd.date_range('2026-11-16', periods=3, freq='D')))
print('B: ', list(pd.date_range('2026-11-20', periods=3, freq='B')))
print('h: ', list(pd.date_range('2026-11-16 09:00', periods=3, freq='h')))
print('ME:', list(pd.date_range('2026-11-16', periods=3, freq='ME')))
Reading the four lines in order: consecutive calendar days; Friday followed
by Monday and Tuesday because the weekend is skipped; three hours on the same
morning; then 30 November, 31 December and 31 January, the respective month
ends. Each entry is a Timestamp, Pandas' type for a single
moment in time.
$ python dr_aliases.py
D: [Timestamp('2026-11-16 00:00:00'), Timestamp('2026-11-17 00:00:00'), Timestamp('2026-11-18 00:00:00')]
B: [Timestamp('2026-11-20 00:00:00'), Timestamp('2026-11-23 00:00:00'), Timestamp('2026-11-24 00:00:00')]
h: [Timestamp('2026-11-16 09:00:00'), Timestamp('2026-11-16 10:00:00'), Timestamp('2026-11-16 11:00:00')]
ME: [Timestamp('2026-11-30 00:00:00'), Timestamp('2026-12-31 00:00:00'), Timestamp('2027-01-31 00:00:00')]
Adding a DateOffset
A DateOffset is a relative time span that respects calendar
rules, such as DateOffset(months=1). Adding it to a DatetimeIndex
moves every label by that span. This differs from adding a fixed number of
days: advancing one month from 31 January lands on 28 February, not on a date
computed by counting days.
import pandas as pd
idx = pd.date_range('2026-01-31', periods=3, freq='ME')
print(idx)
print()
print(idx + pd.DateOffset(months=1))
The original index holds the last days of January, February and March. After
the offset they become 28 February, 28 March and 30 April: the offset adds a
calendar month from each date and clamps to the last valid day where needed.
The resulting index no longer advertises a frequency, shown by
freq=None.
$ python dr_offset.py
DatetimeIndex(['2026-01-31', '2026-02-28', '2026-03-31'],
dtype='datetime64[us]', freq='ME')
DatetimeIndex(['2026-02-28', '2026-03-28', '2026-04-30'],
dtype='datetime64[us]', freq=None)
Shifting a Series with a frequency
The shift method normally moves values while leaving the index
alone. When a freq is supplied, it instead leaves the values in
place and moves the index by that amount. This is convenient for
comparing a value with what happened one period earlier or later.
import pandas as pd
idx = pd.date_range('2026-11-16', periods=3, freq='D')
s = pd.Series([10, 20, 30], index=idx)
print(s)
print()
print(s.shift(1, freq='D'))
The values 10, 20 and 30 are unchanged, but every date is one day later: the
series now runs from 17 to 19 November. The Freq: D line shows
that the shifted index still has a daily frequency.
$ python dr_shift.py 2026-11-16 10 2026-11-17 20 2026-11-18 30 Freq: D, dtype: int64 2026-11-17 10 2026-11-18 20 2026-11-19 30 Freq: D, dtype: int64
Business-day calendars
The offset classes live in pandas.tseries.offsets.
BDay is the business-day equivalent of a calendar day. Adding
BDay(2) advances two weekdays, so a Friday moves to Tuesday
rather than Sunday.
import pandas as pd
from pandas.tseries.offsets import BDay
idx = pd.date_range('2026-11-13', periods=5, freq='B')
print(idx)
print()
print(idx + BDay(2))
The first index starts on Friday 13 November and then jumps to Monday because of the weekend. Adding two business days moves each label forward past the intervening weekend; the last date, Thursday 19 November, becomes Monday 23 November.
$ python dr_bcalendar.py
DatetimeIndex(['2026-11-13', '2026-11-16', '2026-11-17', '2026-11-18',
'2026-11-19'],
dtype='datetime64[us]', freq='B')
DatetimeIndex(['2026-11-17', '2026-11-18', '2026-11-19', '2026-11-20',
'2026-11-23'],
dtype='datetime64[us]', freq=None)
Source
Pandas date_range Documentation, Pandas bdate_range Documentation, Pandas Time Series / Date Functionality, and Pandas DateOffset Documentation
In this article we have generated date ranges with date_range
and bdate_range, used common frequency aliases, moved dates with
DateOffset and shift, and worked with business days.
For individual timestamps and parsing see
Pandas datetime, and for aggregating a time
series into periods see Pandas resampling.
Author
List all Pandas tutorials.