date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize: 'bool' = False, name: 'Hashable' = None, closed: 'str | None | lib.NoDefault' = <no_default>, inclusive: 'str | None' = None, **kwargs) -> '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 :None:None:`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.)

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 :None:None:`this link <https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases>`.

Parameters

start : str or datetime-like, optional

Left bound for generating dates.

end : str or datetime-like, optional

Right bound for generating dates.

periods : int, optional

Number of periods to generate.

freq : str or DateOffset, default 'D'

Frequency strings can have multiples, e.g. '5H'. See here <timeseries.offset_aliases> for a list of frequency aliases.

tz : str or tzinfo, optional

Time zone name for returning localized DatetimeIndex, for example 'Asia/Hong_Kong'. By default, the resulting DatetimeIndex is timezone-naive.

normalize : bool, default False

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

name : str, default None

Name of the resulting DatetimeIndex.

closed : {None, 'left', 'right'}, optional

Make the interval closed with respect to the given frequency to the 'left', 'right', or both sides (None, the default).

deprecated

Argument :None:None:`closed` has been deprecated to standardize boundary inputs. Use :None:None:`inclusive` instead, to set each bound as closed or open.

inclusive : {"both", "neither", "left", "right"}, default "both"

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

versionadded

**kwargs :

For compatibility. Has no effect on the result.

Returns

rng : DatetimeIndex

Return a fixed frequency DatetimeIndex.

See Also

DatetimeIndex

An immutable container for datetimes.

interval_range

Return a fixed frequency IntervalIndex.

period_range

Return a fixed frequency PeriodIndex.

timedelta_range

Return a fixed frequency TimedeltaIndex.

Examples

Specifying the values

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

Specify :None:None:`start` and :None:None:`end`, with the default daily frequency.

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`start` and periods , the number of periods (days).

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`end` and periods , the number of periods (days).

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`start`, :None:None:`end`, and periods ; the frequency is generated automatically (linearly spaced).

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`freq` (frequency) to 'M' (month end frequency).

This example is valid syntax, but we were not able to check execution

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

Multiples are allowed

This example is valid syntax, but we were not able to check execution

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

:None:None:`freq` can also be specified as an Offset object.

This example is valid syntax, but we were not able to check execution

>>> 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='3M')

Specify :None:None:`tz` to set the timezone.

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`start` and :None:None:`end` that are on the boundary. The default, "both", includes boundary points on either end.

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`end` if it falls on the boundary.

This example is valid syntax, but we were not able to check execution

>>> 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 :None:None:`start` if it falls on the boundary, and similarly inclusive='neither' will exclude both :None:None:`start` and :None:None:`end`.

This example is valid syntax, but we were not able to check execution

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

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

pandas.core.indexes.datetimes.DatetimeIndex

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/core/indexes/datetimes.py#879
type: <class 'function'>
Commit: