Skip to content

Pandas date_range: How to Create a Date Range in Pandas

Creating Date Ranges with Pandas Cover Image

In this tutorial, we’re diving deep into one of the essential and versatile tools of the Pandas library—the date_range function. Whether you’re a beginner just starting to explore the power of Pandas or already an adept user, this function is one you’ll definitely want to have in your Python toolbox. This will open up your ability to work with dates and times in Pandas.

Mastering the Pandas date_range function will open up a world of possibilities for your time series data analysis. By the end of this tutorial, you’ll not only understand how to use the date_range function to its full potential, but also how to create custom date ranges with specified frequencies, intervals, and periods for a variety of real-world applications.

So, put on your learning cap and buckle up for an engaging journey into the fantastic realm of Pandas and its date_range function.

The Pandas Date Range Function

Let’s take a look at the Pandas date_range function available in Pandas. The function provides a large number of different parameters and default arguments.

# Understanding the Pandas date_range Function
pd.date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive=None)

Before going further, let’s break down these parameters a bit further. It’s important to note that exactly three of the following four parameters must be specified for the function to work: start=, end=, periods=, and freq=.

ParameterDescriptionDefault ArgumentAccepted Values
startThe left bound for generating datesNonestring or datetime-like
endThe right bound for generating datesNonestring or datetime-like
periodsThe number of periods to generateNoneint
freqFrequencies to use to generate rangesDstring or Dateoffset
tzThe time zone name for timezone-aware date-time valuesNonestring or timezone info
normalizeWhether to normalize start/end dates to midnight before generating the date rangeFalseboolean
nameName of the resulting DatetimeIndexNonestring
inclusiveWhich boundaries to include'both'
{“both”, “neither”, “left”, “right”}
The parameters of the Pandas date_range() function

The function replaced the former closed= parameter with the much more powerful inclusive= parameter in January 2022 in version 1.4.

Let’s now dive into creating our first date range, using the Pandas date_range() function.

Creating a Simple Date Range with Pandas date_range

The simplest type of date range we can create with the Pandas date_range() function is to provide a start date, end date, and a frequency (which defaults to “D” for day). Let’s see how we can create a date range that includes the days between July 1, 2023 and July 7, 2023:

# Create a Simple Date Range in Pandas
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01', '2023-07-02', '2023-07-03', '2023-07-04',
            #    '2023-07-05', '2023-07-06', '2023-07-07'],
            #   dtype='datetime64[ns]', freq='D')

In the code block above, we create a Pandas date range object using the pd.date_range() function. In this case, we passed in only two arguments, those corresponding to the start= and end= parameters. By default, the function will use a frequency of 'D', meaning it separates each value by a day.

Let’s explore this dates object a little bit further by printing out its type:

# Checking the Type of a Date Range Object
print(type(dates))

# Returns:
# <class 'pandas.core.indexes.datetimes.DatetimeIndex'>

We can see that by inspecting the type of object that it returns a DatetimeIndex. This means that Pandas creates a very performant object.

Let’s look at some other types of date ranges that we can create, by customizing the frequencies used.

Creating Date Ranges with Custom Frequencies in Pandas

By default, Pandas uses a frequency of 'D', meaning that each item is one day apart. However, we can also specify our own frequencies by using a frequency string. The table below breaks down a few of the important frequency strings. This is similar to accessing date parts of a date in Pandas.

AliasDescription
Bbusiness day frequency
Ccustom business day frequency
Dcalendar day frequency
Wweekly frequency
Mmonth end frequency
SMsemi-month end frequency (15th and end of month)
BMbusiness month end frequency
BHbusiness hour frequency
Hhourly frequency
T, minminutely frequency
Some key format strings for datetime frequencies

Let’s see how we can create a date range using the Pandas date_range() function where the values are split by semi-month frequency. We’ll create a date range from July 1, 2023 to September 31, 2023:

# Create a Date Range in Pandas with a Custom Frequency
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-08-31', freq='SM')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-15', '2023-07-31', '2023-08-15', '2023-08-31'], dtype='datetime64[ns]', freq='SM-15')

In the code block above, we passed the start and end dates from July 1, 2023, to September 31, 2023. We used a frequency of semi-monthly dates, which uses the 15th of a month and the last day of a month. Because of this, the first of July is ignored. You can learn more about custom frequency strings by checking out the official documentation.

Using a Multiple of a Custom Frequency in Pandas date_range

We can take this one step further by specifying multiples of a custom frequency. For example, if we wanted to create a date range that skips every second day, we could use freq='2D'. Let’s see how we can replicate our earlier example with this frequency:

# Create a Custom Date Range in Pandas
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', freq='2D')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01', '2023-07-03', '2023-07-05', '2023-07-07'], dtype='datetime64[ns]', freq='2D')

In the code block above, we specified a frequency of '2D', which represents two-days. This means that we start on the first day specified, then generate every second day until the end. This process is much easier than adding dates to a date in a Pandas.

Creating Date Ranges with Specific Periods

So far, we have explored using start and end dates when creating a date range. This means that Pandas determines how many values to include. We can also specify the number of values to generate by using the periods= parameter.

Let’s see how we can create a date range that contains five values between July 1-20, 2023:

# Create a Custom Date Range with Specific Periods
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-20', periods=5)
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01 00:00:00', '2023-07-05 18:00:00',
#                '2023-07-10 12:00:00', '2023-07-15 06:00:00',
#                '2023-07-20 00:00:00'],
            #   dtype='datetime64[ns]', freq=None)

In the code block above, we specified three parameters: start, end, and periods. Because of this, we didn’t specify the freq= parameter, meaning that it’s up to Pandas to determine what frequency to use!

Similarly, we can not specify the end of a date range, allowing us to specify the periods and frequency. Let’s explore this in the following section.

Creating Date Ranges with Specific Periods and Frequencies

Because the Pandas date_range() function requires three of the four parameters of start=, end=, periods=, and freq=, we can omit the end= parameter. This allows us to specify a start value, a frequency and a number of periods.

Let’s see what this can look like:

# Create a Custom Date Range with Specific Periods and Frequencies
import pandas as pd
dates = pd.date_range('2023-07-01', freq='B', periods=5)
print(dates)

# Returns:
# DatetimeIndex(['2023-07-03', '2023-07-04', '2023-07-05', '2023-07-06',
#                '2023-07-07'],
#               dtype='datetime64[ns]', freq='B')

In the code block above, we specified that we wanted to create a date range containing business days only, starting on July 1, 2023 for five periods. Because July 1, 2023 was a Saturday, the range actually starts on July 3, 2023.

Changing the Boundaries of a Pandas Date Range

By default, the Pandas date_range function will include both the start and end dates of the range. This is because the Pandas uses inclusive='both'. We can pass in the following options to modify this behavior:

  • “both”, which includes both values
  • “neither”, which excludes both values
  • “left”, which includes only the left value
  • “right”, which includes only the right value

Let’s see how we can omit both of the values by replicating our first example:

# Modifying Edge Behavior in a Pandas Date Range
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', inclusive='neither')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-02', '2023-07-03', '2023-07-04', '2023-07-05',
#                '2023-07-06'],
#               dtype='datetime64[ns]', freq='D')

In the example above, we passed in a daily frequency from July 1 to July 7, 2023. However, we changed the inclusive= parameter to omit both sides of the range. Because of this, both the start and the end values are excluded.

Including Time Zones When Creating a Pandas Date Range

By default, the values in a Pandas date range will be timezone-naive, meaning that timezone information isn’t captured. We can specify a particular timezone by using the name of the timezone that we want to use. For example, let’s specify the Eastern US timezone by passing in 'US/Eastern' as the timezone.

In order to specify a timezone by using the tz= parameter. Let’s see what this looks like below:

# Create a Date Range in Pandas with Timezones
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', tz='US/Eastern')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01 00:00:00-04:00', '2023-07-02 00:00:00-04:00',
#                '2023-07-03 00:00:00-04:00', '2023-07-04 00:00:00-04:00',
#                '2023-07-05 00:00:00-04:00', '2023-07-06 00:00:00-04:00',
#                '2023-07-07 00:00:00-04:00'],
#               dtype='datetime64[ns, US/Eastern]', freq='D')

We can see that the values in the resulting date range above now include timezone information, specific to the US/Eastern timezone.

Changing the Name of the Index of a Pandas Date Range

In this final section, we’ll explore how to change the name of the resulting index. Because the Pandas date_range() function returns an index-style object, this will modify the underlying structure. Let’s see how we can specify an index name using the name= parameter:

# Create a Date Range in Pandas with an Index Name
import pandas as pd
dates = pd.date_range('2023-07-01', '2023-07-07', name='Date')
print(dates)

# Returns:
# DatetimeIndex(['2023-07-01', '2023-07-02', '2023-07-03', '2023-07-04',
#                '2023-07-05', '2023-07-06', '2023-07-07'],
#               dtype='datetime64[ns]', name='Date', freq='D')

In the example above, we can see that the name= attribute is now also included in the date range. When we create a DataFrame with this, this label is also applied to the index. Let’s see what looks like:

# Create a DateFrame in Pandas with an Index Name
import pandas as pd
df = pd.DataFrame(range(7), columns=['Num'], index=pd.date_range('2023-07-01', '2023-07-07', name='Date'))
print(df)

# Returns:
#             Num
# Date           
# 2023-07-01    0
# 2023-07-02    1
# 2023-07-03    2
# 2023-07-04    3
# 2023-07-05    4
# 2023-07-06    5
# 2023-07-07    6

We can see in the DataFrame above that the index now has a name, 'Date'.

Conclusion: Creating Date Ranges with Pandas

In conclusion, we’ve successfully covered the fundamentals of the Pandas date_range function, delving into its numerous applications and customizations that allow us to tackle a wide variety of time series data challenges with ease. We explored everything from crafting custom date ranges with specified frequencies and periods, to fine-tuning timezones and index names to better fit our requirements.

You can learn more about the function by visiting the official documentation.

Nik Piepenbreier

Nik is the author of datagy.io and has over a decade of experience working with data analytics, data science, and Python. He specializes in teaching developers how to use Python for data science using hands-on tutorials.View Author posts

3 thoughts on “Pandas date_range: How to Create a Date Range in Pandas”

  1. Pingback: Pandas Diff: Calculate the Difference Between Pandas Rows • datagy

  2. If we pick start date from any other date except 1st of the specified month, let’s say 03/07/2023 instead of 01/07/2023 in our case then it’s not picking up the 7th month to generate the dates with the frequency of ‘MS'(starting of the month). How I can do the same in order to consider the 7th month as well if I want to start from other date apart from 1st?

    Thanks in advance!

Leave a Reply

Your email address will not be published. Required fields are marked *