ZetCode

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.

dr_range.py
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.

dr_periods.py
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.

dr_bdate.py
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.

dr_aliases.py
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.

dr_offset.py
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.

dr_shift.py
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.

dr_bcalendar.py
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

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.