# xarray.date_range

### xarray.date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive='both', unit='ns', calendar='standard', use_cftime=None)[[source]](https://github.com/pydata/xarray/blob/main/xarray/coding/cftime_offsets.py#L1258-L1496)

Return a fixed frequency datetime index.

The type ([`xarray.CFTimeIndex`](xarray.CFTimeIndex.html.md#xarray.CFTimeIndex) or [`pandas.DatetimeIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html#pandas.DatetimeIndex))
of the returned index depends on the requested calendar and on use_cftime.

* **Parameters:**
  * **start** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) or `datetime-like`, *optional*) – Left bound for generating dates.
  * **end** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) or `datetime-like`, *optional*) – Right bound for generating dates.
  * **periods** ([`int`](https://docs.python.org/3/builtins/functions.html#int), *optional*) – Number of periods to generate.
  * **freq** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) or [`None`](https://docs.python.org/3/builtins/constants.html#None), *default*: `"D"`) – Frequency strings can have multiples, e.g. “5h” and negative values, e.g. “-1D”.
  * **tz** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) or `tzinfo`, *optional*) – Time zone name for returning localized DatetimeIndex, for example
    ‘Asia/Hong_Kong’. By default, the resulting DatetimeIndex is
    timezone-naive. Only valid with pandas DatetimeIndex.
  * **normalize** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), *default*: [`False`](https://docs.python.org/3/builtins/constants.html#False)) – Normalize start/end dates to midnight before generating date range.
  * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str), *default*: [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Name of the resulting index
  * **inclusive** (`{"both", "neither", "left", "right"}`, *default*: `"both"`) – Include boundaries; whether to set each bound as closed or open.

    #### Versionadded
    Added in version 2023.02.0.
  * **unit** (`{"s", "ms", "us", "ns"}`, *default* `"ns"`) – Specify the desired resolution of the result.

    #### Versionadded
    Added in version 2024.12.0.
  * **calendar** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str), *default*: `"standard"`) – Calendar type for the datetimes.
  * **use_cftime** (`boolean`, *optional*) – If True, always return a CFTimeIndex.
    If False, return a pd.DatetimeIndex if possible or raise a ValueError.
    If None (default), return a pd.DatetimeIndex if possible,
    otherwise return a CFTimeIndex. Overridden to False if tz is not None.
* **Returns:**
  [`CFTimeIndex`](xarray.CFTimeIndex.html.md#xarray.CFTimeIndex) or `pd.DatetimeIndex`

### Notes

When `use_cftime=True`, or a calendar other than “standard”, “gregorian”,
or “proleptic_gregorian” is provided, this function is an analog of `pandas.date_range`
for use in generating sequences of `cftime.datetime` objects.  It supports most of the
features of `pandas.date_range` (e.g. specifying how the index is
`closed` on either side, or whether or not to `normalize` the start and
end bounds); however, there are some notable exceptions:

- You cannot specify a `tz` (time zone) argument.
- Start or end dates specified as partial-datetime strings must use the
  [ISO-8601 format](https://en.wikipedia.org/wiki/ISO_8601).
- It supports many, but not all, frequencies supported by
  `pandas.date_range`.  For example it does not currently support any of
  the business-related or semi-monthly frequencies.
- Compound sub-monthly frequencies are not supported, e.g. ‘1H1min’, as
  these can easily be written in terms of the finest common resolution,
  e.g. ‘61min’.

Valid simple frequency strings for use with `cftime`-calendars include
any multiples of the following.

| Alias   | Description             |
|---------|-------------------------|
| YE      | Year-end frequency      |
| YS      | Year-start frequency    |
| QE      | Quarter-end frequency   |
| QS      | Quarter-start frequency |
| ME      | Month-end frequency     |
| MS      | Month-start frequency   |
| D       | Day frequency           |
| h       | Hour frequency          |
| min     | Minute frequency        |
| s       | Second frequency        |
| ms      | Millisecond frequency   |
| us      | Microsecond frequency   |

Any multiples of the following anchored offsets are also supported.

| Alias      | Description                                                      |
|------------|------------------------------------------------------------------|
| Y(E,S)-JAN | Annual frequency, anchored at the (end, beginning) of January    |
| Y(E,S)-FEB | Annual frequency, anchored at the (end, beginning) of February   |
| Y(E,S)-MAR | Annual frequency, anchored at the (end, beginning) of March      |
| Y(E,S)-APR | Annual frequency, anchored at the (end, beginning) of April      |
| Y(E,S)-MAY | Annual frequency, anchored at the (end, beginning) of May        |
| Y(E,S)-JUN | Annual frequency, anchored at the (end, beginning) of June       |
| Y(E,S)-JUL | Annual frequency, anchored at the (end, beginning) of July       |
| Y(E,S)-AUG | Annual frequency, anchored at the (end, beginning) of August     |
| Y(E,S)-SEP | Annual frequency, anchored at the (end, beginning) of September  |
| Y(E,S)-OCT | Annual frequency, anchored at the (end, beginning) of October    |
| Y(E,S)-NOV | Annual frequency, anchored at the (end, beginning) of November   |
| Y(E,S)-DEC | Annual frequency, anchored at the (end, beginning) of December   |
| Q(E,S)-JAN | Quarter frequency, anchored at the (end, beginning) of January   |
| Q(E,S)-FEB | Quarter frequency, anchored at the (end, beginning) of February  |
| Q(E,S)-MAR | Quarter frequency, anchored at the (end, beginning) of March     |
| Q(E,S)-APR | Quarter frequency, anchored at the (end, beginning) of April     |
| Q(E,S)-MAY | Quarter frequency, anchored at the (end, beginning) of May       |
| Q(E,S)-JUN | Quarter frequency, anchored at the (end, beginning) of June      |
| Q(E,S)-JUL | Quarter frequency, anchored at the (end, beginning) of July      |
| Q(E,S)-AUG | Quarter frequency, anchored at the (end, beginning) of August    |
| Q(E,S)-SEP | Quarter frequency, anchored at the (end, beginning) of September |
| Q(E,S)-OCT | Quarter frequency, anchored at the (end, beginning) of October   |
| Q(E,S)-NOV | Quarter frequency, anchored at the (end, beginning) of November  |
| Q(E,S)-DEC | Quarter frequency, anchored at the (end, beginning) of December  |

Finally, the following calendar aliases are supported.

| Alias               | Date type                           | Available use_cftime=False   |
|---------------------|-------------------------------------|------------------------------|
| standard, gregorian | `cftime.DatetimeGregorian`          | True                         |
| proleptic_gregorian | `cftime.DatetimeProlepticGregorian` | True                         |
| noleap, 365_day     | `cftime.DatetimeNoLeap`             | False                        |
| all_leap, 366_day   | `cftime.DatetimeAllLeap`            | False                        |
| 360_day             | `cftime.Datetime360Day`             | False                        |
| julian              | `cftime.DatetimeJulian`             | False                        |

As in the standard pandas function, exactly three of `start`, `end`,
`periods`, or `freq` are required to generate a date range. Note that
`freq` defaults to `"D"` in the event that any of `start`, `end`,
or `periods` are set to `None`. See [`pandas.date_range()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html#pandas.date_range).
for more examples of the behavior of `date_range` with each of the
parameters.

### Examples

<div class="try_examples_button_container"><button class="try_examples_button" onclick="window.tryExamplesShowIframe('65e6919f-2934-4927-b316-1f9de7b2a3c8','668054ef-7c11-40f2-b8e9-fa9a185ea9b3','69f6bdcf-141b-4559-841d-792ea391ccf2','../lite/tree/../notebooks/index.html?path=8964cb72_31b1_41b7_bc53_667101ad504e.ipynb','None')">Try it in your browser!</button></div>

This function returns a `CFTimeIndex`, populated with `cftime.datetime`
objects associated with the specified calendar type, e.g.

```pycon
>>> xr.date_range(
...     start="2000", periods=6, freq="2MS", calendar="noleap", use_cftime=True
... )
CFTimeIndex([2000-01-01 00:00:00, 2000-03-01 00:00:00, 2000-05-01 00:00:00,
             2000-07-01 00:00:00, 2000-09-01 00:00:00, 2000-11-01 00:00:00],
            dtype='object', length=6, calendar='noleap', freq='2MS')
```

<div id="69f6bdcf-141b-4559-841d-792ea391ccf2" class="try_examples_outer_iframe  hidden"><div class="try_examples_button_container"><button class="try_examples_button" onclick="window.tryExamplesHideIframe('65e6919f-2934-4927-b316-1f9de7b2a3c8','69f6bdcf-141b-4559-841d-792ea391ccf2')">Go Back</button><button class="try_examples_button" onclick="window.openInNewTab('65e6919f-2934-4927-b316-1f9de7b2a3c8','69f6bdcf-141b-4559-841d-792ea391ccf2')">Open In Tab</button></div><div id="668054ef-7c11-40f2-b8e9-fa9a185ea9b3" class="jupyterlite_sphinx_iframe_container"></div></div><script>document.addEventListener("DOMContentLoaded", function() {window.loadTryExamplesConfig("../try_examples.json");});</script>

#### SEE ALSO
[`pandas.date_range`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html#pandas.date_range), [`cftime_range`](xarray.cftime_range.html.md#xarray.cftime_range), [`date_range_like`](xarray.date_range_like.html.md#xarray.date_range_like)