Value	Description
`"left"`	The lower bound becomes inclusive. The upper bound becomes exclusive.
`"right"`	The lower bound becomes exclusive. The upper bound becomes inclusive.
`None`	Both bounds are inclusive.

By default, closed=None.

Return Value

A DatetimeIndex.

Examples

Basic usage

To create a sequence of dates from 2020-12-25 to 2020-12-27 (both inclusive):


        
        
            
                
                
                    pd.date_range(start="2020-12-25", end="2020-12-27")
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')

The default step-size (the frequency) is a day, so this is why we see freq="D" in the output.

You could also use datetime-like objects for start and end:


        
        
            
                
                
                    import datetime
datetime_tomorrow = datetime.date.today() + datetime.timedelta(days=1)
pd.date_range(start=datetime.date.today(), end=datetime_tomorrow)
                
            
            DatetimeIndex(['2020-09-02', '2020-09-03'], dtype='datetime64[ns]', freq='D')

Specifying the period

To create a sequence of dates of length 3 from 2020-12-25 (inclusive):


        
        
            
                
                
                    pd.date_range(start="2020-12-25", periods=3)
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')

Specifying the frequency

The frequency can be thought of as the step-size. The default frequency is 1 day:


        
        
            
                
                
                    pd.date_range(start="2020-12-25", periods=3)   # freq="D"
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')

Let's try a 2-day interval:


        
        
            
                
                
                    pd.date_range(start="2020-12-25", periods=3, freq="2D")
                
            
            DatetimeIndex(['2020-12-25', '2020-12-27', '2020-12-29'], dtype='datetime64[ns]', freq='2D')

Let's now try a 1-month interval:


        
        
            
                
                
                    pd.date_range(start="2020-12-25", periods=3, freq="M")
                
            
            DatetimeIndex(['2020-12-31', '2021-01-31', '2021-02-28'], dtype='datetime64[ns]', freq='M')

If the frequency is set to months, the day unit of our start parameter becomes irrelevant - the day will always be set to the end of the month.

Specifying the timezone

Instead of the default dates that are unaware of timezones, we can explicitly specify a timezone using the tz parameter:


        
        
            
                
                
                    pd.date_range(start="2020-12-25", periods=3, tz="Europe/Paris")
                
            
            DatetimeIndex(['2020-12-25 00:00:00+01:00',
               '2020-12-26 00:00:00+01:00',
               '2020-12-27 00:00:00+01:00'],
               dtype='datetime64[ns, Europe/Paris]', freq='D')

Notice how we have +01:00 appended to the Datetimes, which denotes a UTC offset of +1 hour.

Normalising dates

By default, the method will follow the time unit (e.g. the hour of the day) if you specify one:


        
        
            
                
                
                    pd.date_range(start="2020-12-25 05:15:20", periods=3)
                
            
            DatetimeIndex(['2020-12-25 05:15:20',
               '2020-12-26 05:15:20',
               '2020-12-27 05:15:20'],
               dtype='datetime64[ns]', freq='D')

We can set the time of the dates to midnight by setting normalize=True:


        
        
            
                
                
                    pd.date_range(start="2020-12-25 05:15:20", periods=3, normalize=True)
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')

Specifying a name

To give a name to the resulting DatetimeIndex:


        
        
            
                
                
                    pd.date_range(start="2020-12-25", periods=2, name="My Dates")
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26'], dtype='datetime64[ns]', name='My Dates', freq='D')

Notice how we have name="My Dates" encoded into the DatetimeIndex.

Specifying the close

By default, closed=None, which means that the lower and upper bounds are both inclusive:


        
        
            
                
                
                    pd.date_range(start="2020-12-25", end="2020-12-27")
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')

To make the lower bound inclusive and upper bound exclusive, set closed="left":


        
        
            
                
                
                    pd.date_range(start="2020-12-25", end="2020-12-27", closed="left")
                
            
            DatetimeIndex(['2020-12-25', '2020-12-26'], dtype='datetime64[ns]', freq='D')

To make the lower bound exclusive and upper bound inclusive, set closed="right":


        
        
            
                
                
                    pd.date_range(start="2020-12-25", end="2020-12-27", closed="right")
                
            
            DatetimeIndex(['2020-12-26', '2020-12-27'], dtype='datetime64[ns]', freq='D')

Creating a DataFrame with DatetimeIndex

The date_range(~) method can be used to initialise a DataFrame with DatetimeIndex like so:


        
        
            
                
                
                    index_date = pd.date_range("2020-12-25", periods=4, freq="3H")
df = pd.DataFrame({"A":["a","b","c","d"]}, index=index_date)
df
                
            
                                 A
2020-12-25 00:00:00  a
2020-12-25 03:00:00  b
2020-12-25 06:00:00  c
2020-12-25 09:00:00  d