Pandas pd.to_datetime() Function

Pandas 通用函数 Common Pandas Functions

pd.to_datetime()is a function in the Pandas library used toconvert data to the datetime typeIt can convert data in various formats, such as strings, Unix timestamps, etc., to Pandas' datetime64 type.

Datetime processing is a common task in data analysis. After converting to the datetime type, you can conveniently perform operations such as date extraction, time arithmetic, and timezone handling.

Term Explanation： to_datetimeIt means "convert to datetime", i.e., uniformly converting time data in various formats into standard datetime objects.

Basic Syntax and Parameters

pd.to_datetime()is a top-level function in the Pandas library, used to convert time data in various formats to the datetime type.

Syntax Format

pd.to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc=False, format=None, unit='ns')

Parameter Description

Parameter	Type	Description
arg	Integer, float, string, datetime, list, Series	The data to be converted to datetime type.
errors	String	Error handling method: 'raise' (default) raises an exception; 'coerce' converts to NaT; 'ignore' returns the original data.
dayfirst	Boolean	If True, the day is placed before the month (e.g., 01/02/2023 means the 2nd).
utc	Boolean	If True, returns a datetime in the UTC timezone.
format	String	Specifies the datetime format, such as '%Y-%m-%d'.
unit	String	When arg is numeric, specifies the unit: 'D', 's', 'ms', 'us', 'ns'.

Return Value Description

Return value: Returns a Series of type datetime64.
Effect: Converts the input data to Pandas' datetime type, making it easy to perform datetime operations.

Examples

Let's thoroughly master, through a series of examples from simple to complex,pd.to_datetime()its usage.

Example 1: Basic Usage - Converting Strings to Datetime

Examples

import pandas as pd

# 1. Create a datetime string Series
dates = pd.Series([
'2023-01-01',
'2023-01-02',
'2023-01-03',
'2023-01-04',
'2023-01-05'
])

print("=== Original Series (type:", dates.dtype, "）===")
print(dates)

# 2. Use pd.to_datetime() to convert to datetime type
result = pd.to_datetime(dates)
print("\n=== After pd.to_datetime() conversion (type:", result.dtype, "）===")
print(result)

# 3. Supports multiple formats
dates_mixed = pd.Series([
'2023-01-01',
'2023/02/03',
'01.04.2023',
'May 6, 2023'
])
print("\n=== Automatic parsing of multiple formats ===)
print(pd.to_datetime(dates_mixed))

# 4. Information containing time
dates_with_time = pd.Series([
'2023-01-01 12:30:45',
'2023-02-03 08:15:30'
])
result_datetime = pd.to_datetime(dates_with_time)
print("\n=== Information containing time ===)
print(result_datetime)

Run result:

=== 原始 Series（类型： object ）===
0    2023-01-01
1    2023-01-02
2    2023-01-03
3    2023-01-04
4    2023-01-05
dtype: object

=== pd.to_datetime() 转换后（类型： datetime64[ns] ）===
0   2023-01-01 00:00:00
1   2023-01-02 00:00:00
2   2023-01-03 00:00:00
3   2023-01-04 00:00:00
4   2023-01-05 00:00:00

=== 多种格式自动解析 ===
0   2023-01-01 00:00:00
1   2023-02-03 00:00:00
2   2023-04-01 00:00:00
3   2023-05-06 00:00:00

=== 包含时间的信息 ===
0   2023-01-01 12:30:45
1   2023-02-03 08:15:30

Code explanation:

pd.to_datetime()It can automatically recognize various common datetime formats.
Even if the input only contains a date, the time part defaults to 00:00:00.
It can handle date formats with different separators, such as Chinese characters, dots, and slashes.

Example 2: Handling Different Date Formats and the dayfirst Parameter

For date formats in different regions, you can use thedayfirstparameter or theformatparameter.

Examples

import pandas as pd

# 1. European format date (month/day/year)
europe_dates = pd.Series(['01/02/2023', '02/03/2023', '03/04/2023'])

print("=== European format date (01/02/2023 interpreted as the 2nd) ===")
print("Default (month/day/year):", pd.to_datetime(europe_dates).dt.day.tolist())
print("dayfirst=True:", pd.to_datetime(europe_dates, dayfirst=True).dt.day.tolist())

# 2. Use the format parameter to specify the exact format
print("\n=== Using the format parameter ===)
result = pd.to_datetime('2023-06-15 14:30:00', format='%Y-%m-%d %H:%M:%S')
print(f"Conversion result: {result}")

# 3. Complex format parsing
complex_dates = pd.Series(['December 25, 2023', '15/08/2023', '2023-05-01'])
print("\n=== Automatic parsing of mixed formats ===)
print(pd.to_datetime(complex_dates, dayfirst=True))

Run result:

=== 欧洲格式日期（01/02/2023 理解为 2 号）===
默认: [1, 2, 3]
dayfirst=True: [2, 3, 4]

=== 使用 format 参数 ===
转换结果: 2023-06-15 14:30:00

=== 混合格式自动解析 ===
0   2023-12-25 00:00:00
1   2023-08-15 00:00:00
2   2023-05-01 00:00:00

Code explanation:

formatThe parameter specifies the exact format, clearly telling Pandas how to parse the date, avoiding ambiguity.
Automatic parsing is very powerful, but when there is ambiguity (such as interpreting 01/02/2023), you need to use thedayfirstorformatparameter to specify explicitly.

Example 3: Converting Unix Timestamps to Datetime

Timestamps exported from databases or systems can be converted using theunitparameter.

Examples

import pandas as pd

# 1. Unix timestamp (seconds)
timestamps = pd.Series([1672531200, 1672617600, 1672704000])

print("=== Unix timestamp (seconds) ===")
print(timestamps.values)

# 2. Convert to datetime
result = pd.to_datetime(timestamps, unit='s')
print("\n=== After pd.to_datetime(..., unit='s') conversion ===)
print(result)

# 3. Unix timestamp (milliseconds)
timestamps_ms = pd.Series([1672531200000, 1672617600000, 1672704000000])
result_ms = pd.to_datetime(timestamps_ms, unit='ms')
print("\n=== Millisecond-level timestamp ===)
print(result_ms)

# 4. Convert from a fixed origin
print("\n=== Calculated from 2023-01-01 ===)
days = pd.Series([0, 1, 2, 3, 4])
result_origin = pd.to_datetime(days, origin='2023-01-01', unit='D')
print(result_origin)

Run result:

=== Unix 时间戳（秒）===
[1672531200 1672617600 1672704000]

=== pd.to_datetime(..., unit='s') 转换后 ===
0   2023-01-01 00:00:00
1   2023-01-02 00:00:00
2   2023-01-03 00:00:00

=== 毫秒级时间戳 ===
0   2023-01-01 00:00:00
1   2023-01-02 00:00:00
2   2023-01-03 00:00:00

=== 从 2023-01-01 开始计算 ===
0   2023-01-01
1   2023-01-02
2   2023-01-03
3   2023-01-04
4   2023-01-05

Code explanation:

unit='s'Means the unit of the value is seconds (Unix timestamp).
unit='ms'Means a millisecond timestamp.
originThe parameter can specify the starting time, used to calculate relative time.

Example 4: Handling Invalid Dates with the errors Parameter

Examples

import pandas as pd
import numpy as np

# 1. Series containing invalid dates
mixed_dates = pd.Series(['2023-01-01', '2023-02-30', 'invalid', '2023-03-15'])

print("=== Series containing invalid dates ===")
print(mixed_dates)

# 2. errors='raise' (default) - raises an exception
print("\n=== errors='raise' ===")
try:
pd.to_datetime(mixed_dates, errors='raise')
except Exception as e:
print(f"Exception: {type(e).__name__}")

# 3. errors='coerce' - converts invalid dates to NaT
print("\n=== errors='coerce' ===")
result = pd.to_datetime(mixed_dates, errors='coerce')
print(result)

# 4. errors='ignore' - keeps as-is
print("\n=== errors='ignore' ===")
result_ignore = pd.to_datetime(mixed_dates, errors='ignore')
print(result_ignore)
print(f"Type: {result_ignore.dtype}")

Run result:

=== 包含无效日期的 Series ===
0    2023-01-01
1    2023-02-30
2    invalid
3    2023-03-15

=== errors='raise' ===
异常: OutOfBoundsDatetime

=== errors='coerce' ===
0   2023-01-01 00:00:00
1                    NaT
2                    NaT
3   2023-03-15 00:00:00

=== errors='ignore' ===
0    2023-01-01
1    2023-02-30
2    invalid
3    2023-03-15
dtype: object

Code explanation:

errors='coerce'Converts both invalid dates and unparseable values to NaT (Not a Time, equivalent to a missing value).
This is very useful when handling dirty data, as it maintains the continuity of data processing.

Notes

Important note:

If a value in the data exceeds the datetime range, it will raise anOutOfBoundsDatetimeexception.

formatThe parameter can explicitly specify the date format. It is recommended to use it when processing large amounts of data to improve performance.

The converted datetime object can use the.dtaccessor for rich datetime operations.

Timezone handling requires installing thepytzlibrary.

Python math 模块 Common Pandas Functions

Other Extensions

Data Reading and Writing

Data Processing Core

Reference Manual

Statistics and Cases

Pandas pd.to_datetime() Function

Basic Syntax and Parameters

Syntax Format

Parameter Description

Return Value Description

Examples

Example 1: Basic Usage - Converting Strings to Datetime

Examples

Example 2: Handling Different Date Formats and the dayfirst Parameter

Examples

Example 3: Converting Unix Timestamps to Datetime

Examples

Example 4: Handling Invalid Dates with the errors Parameter

Examples

Notes