Pandas · Function

pd.Period

pd.Period represents a defined span of time—such as a month, quarter, or year—rather than a single instant. Its freq determines the period's granularity and interpretation.

How it works

pd.Period constructs an object representing an entire time span, such as a month, quarter, or year. Its frequency determines how the value is interpreted; frequency is required when the input value is a datetime. The object can be converted to another frequency or represented as a timestamp.

Syntax

class pandas.Period(*value=None*, *freq=None*, *ordinal=None*, *year=None*, *month=None*, *quarter=None*, *day=None*, *hour=None*, *minute=None*, *second=None*)

Parameters

Name	Type	Description
`value`	`Period, str, datetime, date or pandas.Timestamp`	The time period represented; accepts a Period, string, datetime, date, or pandas Timestamp. Default is None.
`freq`	`str`	A pandas period frequency string or corresponding frequency object. Required when value is a datetime. Default is None.
`ordinal`	`int`	The period offset from the proleptic Gregorian epoch. Default is None.
`year`	`int`	Year component. Default is None.
`month`	`int`	Month component. Default is 1.
`quarter`	`int`	Quarter component. Default is None.
`day`	`int`	Day component. Default is 1.
`hour`	`int`	Hour component. Default is 0.
`minute`	`int`	Minute component. Default is 0.
`second`	`int`	Second component. Default is 0.

Returns

A pandas Period object representing the specified time span.

Key points

Constructs a pandas Period object for a defined span of time.
Use it for intervals instead of single timestamps.
Its model naturally represents calendar durations such as months, quarters, and years.
The frequency controls how pandas interprets and stores the supplied value.
freq accepts pandas period aliases or their corresponding frequency objects.
An ordinal can identify the period by its offset from the proleptic Gregorian epoch.
Use asfreq to change frequency while choosing the interval's start or end.

Common mistakes

A datetime input must be accompanied by an explicit freq; otherwise construction is invalid.
A Period is an interval, not merely its beginning or ending instant; use boundary properties or conversion methods when an endpoint is needed.

Example: Create and convert a period

import pandas as pd

period = pd.Period("2024-01", freq="M")
print(period)
print(period.start_time)
print(period.end_time)
print(period.asfreq("D", how="start"))

Creates a monthly Period, inspects its boundaries, and converts it to a daily period at the interval's start.

When to use it

Represent calendar periods

Model calendar-based intervals such as months, quarters, or years in time-series data.

Change temporal frequency

Translate a broad interval into a finer-grained period at its beginning or end.

Preserve span semantics

Keep an interval distinct from its boundary timestamps when analyzing period-based data.

Interview questions

QHow does Period differ from Timestamp?

pd.Period represents a span of time, while Timestamp represents one instant. The freq argument defines the span's granularity, such as monthly, quarterly, or yearly.

Follow-up: How would you obtain an instant from a Period? Use to_timestamp, selecting an appropriate frequency and optionally the start or end with how.

QWhat are the main inputs to pd.Period?

The value identifies the time period and may be a Period, string, datetime, date, or pandas Timestamp. freq accepts a pandas period frequency string or corresponding frequency object.

Follow-up: What happens when value is a datetime but freq is omitted? Construction cannot determine the intended period frequency, so freq is required.

QHow do you change a Period's frequency?

asfreq converts a Period to another frequency and lets you choose the start or end of the interval. For example, a monthly Period can be represented as a daily Period at its start.

Follow-up: Why might conversion to a finer frequency need an endpoint choice? A broader interval contains multiple finer-grained periods, so how selects which boundary-relative period represents it.

pandas.PeriodIndex
pandas.arrays.PeriodArray
pandas.Timestamp
pandas.Period.asfreq
pandas.Period.to_timestamp
pandas.Period.now

Source: pandas.Period — pandas 3.0.6 documentation. Checked 2026-10-15.