pandas.date_range#

pandas.date_range(start=None,end=None,periods=None,freq=None,tz=None,normalize=False,name=None,inclusive='both',*,unit=None,**kwargs)[source]#

Return a fixed frequency DatetimeIndex.

Returns the range of equally spaced time points (where the difference between anytwo adjacent points is specified by the given frequency) such that they allsatisfystart <[=] x <[=] end, where the first one and the last one are, resp.,the first and last time points in that range that fall on the boundary offreq(if given as a frequency string) or that are valid forfreq (if given as apandas.tseries.offsets.DateOffset). (If exactly one ofstart,end, orfreq isnot specified, this missing parameter can be computedgivenperiods, the number of timesteps in the range. See the note below.)

Parameters:

startstr or datetime-like, optional

Left bound for generating dates.

endstr or datetime-like, optional

Right bound for generating dates.

periodsint, optional

Number of periods to generate.

freqstr, Timedelta, datetime.timedelta, or DateOffset, default ‘D’

Frequency strings can have multiples, e.g. ‘5h’. Seehere for a list offrequency aliases.

tzstr or tzinfo, optional

Time zone name for returning localized DatetimeIndex, for example‘Asia/Hong_Kong’. By default, the resulting DatetimeIndex istimezone-naive unless timezone-aware datetime-likes are passed.

normalizebool, default False

Normalize start/end dates to midnight before generating date range.

namestr, default None

Name of the resulting DatetimeIndex.

inclusive{“both”, “neither”, “left”, “right”}, default “both”

Include boundaries; Whether to set each bound as closed or open.

Added in version 1.4.0.

unitstr, default None

Specify the desired resolution of the result.

Added in version 2.0.0.

**kwargs

For compatibility. Has no effect on the result.

Returns:

DatetimeIndex

See also

DatetimeIndex

An immutable container for datetimes.

timedelta_range

Return a fixed frequency TimedeltaIndex.

period_range

Return a fixed frequency PeriodIndex.

interval_range

Return a fixed frequency IntervalIndex.

Notes

Of the four parametersstart,end,periods, andfreq,exactly three must be specified. Iffreq is omitted, the resultingDatetimeIndex will haveperiods linearly spaced elements betweenstart andend (closed on both sides).

To learn more about the frequency strings, please seethis link.

Examples

Specifying the values

The next four examples generate the sameDatetimeIndex, but varythe combination ofstart,end andperiods.

Specifystart andend, with the default daily frequency.

>>>pd.date_range(start='1/1/2018',end='1/08/2018')DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',               '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'],              dtype='datetime64[ns]', freq='D')

Specify timezone-awarestart andend, with the default daily frequency.

>>>pd.date_range(...start=pd.to_datetime("1/1/2018").tz_localize("Europe/Berlin"),...end=pd.to_datetime("1/08/2018").tz_localize("Europe/Berlin"),...)DatetimeIndex(['2018-01-01 00:00:00+01:00', '2018-01-02 00:00:00+01:00',               '2018-01-03 00:00:00+01:00', '2018-01-04 00:00:00+01:00',               '2018-01-05 00:00:00+01:00', '2018-01-06 00:00:00+01:00',               '2018-01-07 00:00:00+01:00', '2018-01-08 00:00:00+01:00'],              dtype='datetime64[ns, Europe/Berlin]', freq='D')

Specifystart andperiods, the number of periods (days).

>>>pd.date_range(start='1/1/2018',periods=8)DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',               '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'],              dtype='datetime64[ns]', freq='D')

Specifyend andperiods, the number of periods (days).

>>>pd.date_range(end='1/1/2018',periods=8)DatetimeIndex(['2017-12-25', '2017-12-26', '2017-12-27', '2017-12-28',               '2017-12-29', '2017-12-30', '2017-12-31', '2018-01-01'],              dtype='datetime64[ns]', freq='D')

Specifystart,end, andperiods; the frequency is generatedautomatically (linearly spaced).

>>>pd.date_range(start='2018-04-24',end='2018-04-27',periods=3)DatetimeIndex(['2018-04-24 00:00:00', '2018-04-25 12:00:00',               '2018-04-27 00:00:00'],              dtype='datetime64[ns]', freq=None)

Other Parameters

Changed thefreq (frequency) to'ME' (month end frequency).

>>>pd.date_range(start='1/1/2018',periods=5,freq='ME')DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31', '2018-04-30',               '2018-05-31'],              dtype='datetime64[ns]', freq='ME')

Multiples are allowed

>>>pd.date_range(start='1/1/2018',periods=5,freq='3ME')DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',               '2019-01-31'],              dtype='datetime64[ns]', freq='3ME')

freq can also be specified as an Offset object.

>>>pd.date_range(start='1/1/2018',periods=5,freq=pd.offsets.MonthEnd(3))DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',               '2019-01-31'],              dtype='datetime64[ns]', freq='3ME')

Specifytz to set the timezone.

>>>pd.date_range(start='1/1/2018',periods=5,tz='Asia/Tokyo')DatetimeIndex(['2018-01-01 00:00:00+09:00', '2018-01-02 00:00:00+09:00',               '2018-01-03 00:00:00+09:00', '2018-01-04 00:00:00+09:00',               '2018-01-05 00:00:00+09:00'],              dtype='datetime64[ns, Asia/Tokyo]', freq='D')

inclusive controls whether to includestart andend that are on theboundary. The default, “both”, includes boundary points on either end.

>>>pd.date_range(start='2017-01-01',end='2017-01-04',inclusive="both")DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03', '2017-01-04'],              dtype='datetime64[ns]', freq='D')

Useinclusive='left' to excludeend if it falls on the boundary.

>>>pd.date_range(start='2017-01-01',end='2017-01-04',inclusive='left')DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'],              dtype='datetime64[ns]', freq='D')

Useinclusive='right' to excludestart if it falls on the boundary, andsimilarlyinclusive='neither' will exclude bothstart andend.

>>>pd.date_range(start='2017-01-01',end='2017-01-04',inclusive='right')DatetimeIndex(['2017-01-02', '2017-01-03', '2017-01-04'],              dtype='datetime64[ns]', freq='D')

Specify a unit

>>>pd.date_range(start="2017-01-01",periods=10,freq="100YS",unit="s")DatetimeIndex(['2017-01-01', '2117-01-01', '2217-01-01', '2317-01-01',               '2417-01-01', '2517-01-01', '2617-01-01', '2717-01-01',               '2817-01-01', '2917-01-01'],              dtype='datetime64[s]', freq='100YS-JAN')