Skip to main content
`Ctrl`+`K`

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

  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 fall in the range [start, 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 `freq` is positive, the points satisfy start <[=] x <[=] end, and if `freq` is negative, the points satisfy end <[=] x <[=] start. (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:
    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, Timedelta, datetime.timedelta, or DateOffset, default ‘D’

      Frequency strings can have multiples, e.g. ‘5h’. See here 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 unless timezone-aware datetime-likes are passed.

    normalize bool, default False

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

    name Hashable, 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.

    unit{‘s’, ‘ms’, ‘us’, ‘ns’, None}, default None

      Specify the desired resolution of the result. If not specified, this is inferred from the ‘start’, ‘end’, and ‘freq’ using the same inference as `Timestamp` taking the highest resolution of the three that are provided.

      Added in version 2.0.0.

    **kwargs

      For compatibility. Has no effect on the result.

  Returns:
    DatetimeIndex

      A DatetimeIndex object of the generated dates.

  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`, a maximum of three can be specified at once. Of the three parameters `start`, `end`, and `periods`, at least two 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[us]', 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[us, 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[us]', 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[us]', 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[us]', 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[us]', 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[us]', 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[us]', 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[us, 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[us]', 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[us]', 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[us]', 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')