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 any two adjacent points is specified by the given frequency) such that they all satisfy start <[=] 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 of freq (if given as a frequency string) or that are valid for freq (if given as a pandas.tseries.offsets.DateOffset). (If exactly one of start, end, or freq is not specified, this missing parameter can be computed given periods, 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’. See here for a list of frequency aliases.
tzstr or tzinfo, optional: Time zone name for returning localized DatetimeIndex, for example ‘Asia/Hong_Kong’. By default, the resulting DatetimeIndex is timezone-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 parameters start, end, periods, and freq, exactly three must be specified. If freq is omitted, the resulting DatetimeIndex will have periods linearly spaced elements between start and end (closed on both sides).

To learn more about the frequency strings, please see this link.

Examples

Specifying the values

The next four examples generate the same DatetimeIndex, but vary the combination of start, end and periods.

Specify start and end, 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-aware start and end, 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')

Specify start and periods, 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')

Specify end and periods, 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')

Specify start, end, and periods; the frequency is generated automatically (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 the freq (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')

Specify tz 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 include start and end that are on the boundary. 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')

Use inclusive='left' to exclude end 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')

Use inclusive='right' to exclude start if it falls on the boundary, and similarly inclusive='neither' will exclude both start and end.

>>> 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')