pd.to_datetime()
说明
将标量、列表、Series、DataFrame 等各种输入转换为
Timestamp或DatetimeIndex，是最常用的时间解析函数。
参数
| 参数 | 说明 |
|---|---|
| arg | 待转换数据（标量、列表、元组、Series、DataFrame 等） |
| errors | 错误处理方式：'raise'（抛出异常）、'coerce'（转为 NaT）、'ignore'（返回原输入） |
| dayfirst | 是否按「日在前」解析（True 时 01/02/2026 为 2 月 1 日） |
| yearfirst | 是否按「年在先」解析 |
| utc | 为 True 时返回 UTC 时区结果 |
| format | 指定 strftime 解析格式，如 '%Y-%m-%d %H:%M:%S' |
| exact | format 是否必须完全匹配（False 时允许模糊匹配） |
| unit | 数值时间戳单位：'s'、'ms'、'us'、'ns'、'D' 等 |
| infer_datetime_format | 是否自动推断格式（注意：已在 pandas 2.x 弃用） |
| origin | 数值时间戳的参考原点，默认 'unix'（1970-01-01） |
| cache | 是否缓存唯一转换结果以加速重复日期解析 |
示例
import pandas as pd
# 字符串转标量
print(pd.to_datetime('2026-08-19'))
# 2026-08-19 00:00:00
# 列表转 DatetimeIndex
print(pd.to_datetime(['2026-08-19', '2026-08-20']))
# DatetimeIndex(['2026-08-19', '2026-08-20'], dtype='datetime64[ns]', freq=None)
# dayfirst 与 yearfirst
print(pd.to_datetime('01/02/2026', dayfirst=True)) # 2026-02-01
print(pd.to_datetime('01/02/2026', yearfirst=True)) # 2001-02-2026 → 实际为 2026-02-01? 取决于格式Hmm, let me fix that example. dayfirst=True with ‘01/02/2026’ gives 2026-02-01. yearfirst=True with ‘01/02/2026’ - actually to_datetime would parse 01 as year? That’s weird. Better example: ‘2026/01/02’ with yearfirst=False. Let me simplify:
# dayfirst：日在前
print(pd.to_datetime('01/02/2026', dayfirst=True))
# 2026-02-01 00:00:00
# yearfirst：年在先
print(pd.to_datetime('2026/01/02', yearfirst=True))
# 2026-01-02 00:00:00
# errors='coerce'：非法日期转 NaT
print(pd.to_datetime(['2026-08-19', 'invalid'], errors='coerce'))
# DatetimeIndex(['2026-08-19', 'NaT'], dtype='datetime64[ns]', freq=None)
# 指定 format，解析加速且格式严格
print(pd.to_datetime('19-08-2026', format='%d-%m-%Y'))
# 2026-08-19 00:00:00
# 数值时间戳 + unit + origin
print(pd.to_datetime([0, 1, 2], unit='s'))
# DatetimeIndex(['1970-01-01 00:00:00', '1970-01-01 00:00:01', ...], dtype='datetime64[ns]')
print(pd.to_datetime([0, 1], unit='D', origin='2026-01-01'))
# DatetimeIndex(['2026-01-01', '2026-01-02'], dtype='datetime64[ns]')
# utc=True 返回 UTC 时间
print(pd.to_datetime('2026-08-19 13:05:00', utc=True))
# 2026-08-19 13:05:00+00:00pd.to_timedelta()
说明
将字符串、数值或 Series 转换为
Timedelta或TimedeltaIndex。
# 字符串
print(pd.to_timedelta('1 days 02:30:00'))
# 1 days 02:30:00
# 数值 + 单位
print(pd.to_timedelta([1, 2, 3], unit='h'))
# TimedeltaIndex(['0 days 01:00:00', '0 days 02:00:00', '0 days 03:00:00'], dtype='timedelta64[ns]', freq=None)
# errors 通用
print(pd.to_timedelta(['1 day', 'invalid'], errors='coerce'))
# TimedeltaIndex(['1 days', 'NaT'], dtype='timedelta64[ns]', freq=None)pd.date_range()
说明
按指定开始/结束/数量 + 频率生成
DatetimeIndex，是创建规则时间序列的核心函数。
参数
| 参数 | 说明 |
|---|---|
| start | 起始时间（字符串或 Timestamp） |
| end | 结束时间（字符串或 Timestamp） |
| periods | 生成的时间点数量 |
| freq | 频率字符串或 DateOffset，默认 'D' |
| tz | 时区名称或 tzinfo，如 'Asia/Shanghai'、'UTC' |
| normalize | 为 True 时将时间归一化为午夜 0 点 |
| name | 生成索引的名称 |
| inclusive | 包含边界：'both'、'neither'、'left'、'right' |
| unit | 返回索引的精度单位：'s'、'ms'、'us'、'ns' |
示例
# start + end
print(pd.date_range('2026-08-01', '2026-08-05'))
# DatetimeIndex(['2026-08-01', ..., '2026-08-05'], dtype='datetime64[ns]', freq='D')
# periods 指定数量
print(pd.date_range('2026-08-01', periods=3, freq='D'))
# DatetimeIndex(['2026-08-01', '2026-08-02', '2026-08-03'], dtype='datetime64[ns]', freq='D')
# freq 频率
print(pd.date_range('2026-01-01', periods=4, freq='MS')) # 每月第一天
print(pd.date_range('2026-01-01', periods=4, freq='W-MON')) # 每周一
print(pd.date_range('2026-01-01 09:00', periods=4, freq='4h')) # 每 4 小时
# tz 时区
print(pd.date_range('2026-01-01', periods=2, freq='D', tz='Asia/Shanghai'))
# DatetimeIndex(['2026-01-01 00:00:00+08:00', '2026-01-02 00:00:00+08:00'], dtype='datetime64[ns, Asia/Shanghai]', freq='D')
# normalize：归一化到午夜
print(pd.date_range('2026-01-01 14:30', periods=2, freq='D', normalize=True))
# DatetimeIndex(['2026-01-01', '2026-01-02'], dtype='datetime64[ns]', freq='D')
# inclusive：排除端点
print(pd.date_range('2026-01-01', '2026-01-04', inclusive='left'))
# DatetimeIndex(['2026-01-01', '2026-01-02', '2026-01-03'], dtype='datetime64[ns]', freq='D')
# name
print(pd.date_range('2026-01-01', periods=2, name='date_idx'))pd.bdate_range()
说明
date_range的工作日（Business Day）版本，默认自动跳过周末。
print(pd.bdate_range('2026-08-03', periods=5)) # 周一至周五
# DatetimeIndex(['2026-08-03', '2026-08-04', '2026-08-05', '2026-08-06', '2026-08-07'], dtype='datetime64[ns]', freq='B')
# 自定义节假日日历
from pandas.tseries.holiday import USFederalHolidayCalendar
from pandas.tseries.offsets import CustomBusinessDay
cal = USFederalHolidayCalendar()
print(pd.bdate_range('2026-07-01', periods=3, freq=CustomBusinessDay(calendar=cal)))pd.period_range()
说明
生成
PeriodIndex（固定频率区间索引），频率通常为月、季、年等。
print(pd.period_range('2026-01', periods=3, freq='M'))
# PeriodIndex(['2026-01', '2026-02', '2026-03'], dtype='period[M]', freq='M')
print(pd.period_range('2026-Q1', '2026-Q4', freq='Q'))
# PeriodIndex(['2026Q1', '2026Q2', '2026Q3', '2026Q4'], dtype='period[Q-DEC]', freq='Q-DEC')
print(pd.period_range('2026-01-01', '2026-01-07', freq='D'))
# PeriodIndex(['2026-01-01', ..., '2026-01-07'], dtype='period[D]', freq='D')pd.timedelta_range()
说明
生成
TimedeltaIndex，用于构造规律的时间差序列。
print(pd.timedelta_range(start='1 day', periods=4))
# TimedeltaIndex(['1 days', '2 days', '3 days', '4 days'], dtype='timedelta64[ns]', freq='D')
print(pd.timedelta_range(start='00:00:00', end='00:00:03', freq='s'))
# TimedeltaIndex(['0 days 00:00:00', ..., '0 days 00:00:03'], dtype='timedelta64[ns]', freq='s')pd.interval_range()
说明
生成
IntervalIndex，常用于分段统计（如年龄区间、价格区间）。
print(pd.interval_range(start=0, end=4, periods=4))
# IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4]], name='None', dtype='interval[int64, right]')
print(pd.interval_range(start=pd.Timestamp('2026-01-01'), periods=3, freq='D'))
# IntervalIndex([(2026-01-01, 2026-01-02], (2026-01-02, 2026-01-03], (2026-01-03, 2026-01-04]], dtype='interval[datetime64[ns], right]')