Introduction

pandas.resample is the time-series equivalent of groupby: it groups rows into time buckets and then lets you aggregate or fill them. It is most useful when your data has a datetime index or when you point resample at a datetime column with on=. Once that requirement is satisfied, you can downsample, upsample, and control how the time bins are labeled.

Start with a Datetime Index

The most common pattern is a Series or DataFrame indexed by timestamps.

1import pandas as pd
2
3df = pd.DataFrame(
4    {
5        "sales": [10, 20, 15, 30],
6    },
7    index=pd.to_datetime(
8        [
9            "2025-01-01 09:15",
10            "2025-01-01 09:45",
11            "2025-01-01 10:05",
12            "2025-01-01 10:50",
13        ]
14    ),
15)
16
17hourly = df.resample("1H").sum()
18print(hourly)

"1H" is the resampling rule, meaning one-hour buckets. Because we call .sum(), all rows inside each hour are aggregated together.

Downsampling Means Combining Smaller Intervals

Downsampling reduces frequency, such as minute data into hourly data or daily data into monthly data. The aggregation step is required because each output bucket represents multiple input rows.

Common aggregations include:

• '.sum() for totals.'
• '.mean() for averages.'
• '.max() and .min() for extremes.'
• '.agg() for multiple calculations at once.'

1summary = df.resample("1H").agg({
2    "sales": ["sum", "mean", "max"]
3})
4print(summary)

This is especially useful for monitoring, financial data, and sensor streams where raw timestamps are too fine-grained for the question you want to answer.

Upsampling Creates Empty Time Slots

Upsampling moves to a higher frequency, such as hourly data to 15-minute intervals. That creates new timestamps where no original data exists, so the immediate result contains missing values.

upsampled = hourly.resample("15min").asfreq()
print(upsampled)

Once the empty rows exist, you can decide how to fill them:

forward_filled = hourly.resample("15min").ffill()
print(forward_filled)

Use forward fill only when carrying the last known value forward is logically correct. For state measurements such as temperature or account balance, that may be reasonable. For event counts or transactions, it is often wrong.

Use on= When the Datetime Is a Column

You do not have to move the datetime into the index. If the timestamps live in a column, pass that column name to on=.

1import pandas as pd
2
3df = pd.DataFrame(
4    {
5        "timestamp": pd.to_datetime([
6            "2025-01-01 09:15",
7            "2025-01-01 09:45",
8            "2025-01-01 10:05",
9        ]),
10        "sales": [10, 20, 15],
11    }
12)
13
14result = df.resample("1H", on="timestamp").sum()
15print(result)

This is convenient when you want to preserve an existing index or avoid reshaping the frame.

label and closed Control Bucket Semantics

Time bins have edges, so it matters which side is closed and which timestamp labels the result. For example, a one-hour bucket can be labeled at the start or the end of the interval.

df.resample("1H", label="right", closed="right").sum()

These options matter most when you compare pandas results against database reports, dashboards, or business definitions that specify how interval boundaries should behave.

Resampling Is Only as Good as the Time Data

If the index is not actually datetime-like, resample will fail. If the timestamps have mixed time zones or unexpected gaps, the result may be technically correct but analytically misleading. Always validate the timestamp column before trusting the aggregate.

Common Pitfalls

• Calling resample on an index that is not datetime-like.
• Forgetting that downsampling requires an aggregation step.
• Upsampling and then filling missing values with a method that changes the meaning of the data.
• Ignoring label and closed when interval boundaries matter.
• Assuming resample sorts and cleans bad timestamps for you.

Summary

• 'resample groups time-series data into new frequency buckets.'
• Use a datetime index or pass a datetime column with on=.
• Downsampling combines multiple rows and requires aggregation.
• Upsampling creates empty time slots that you may need to fill explicitly.
• Pay attention to interval labeling and boundary rules when accuracy matters.