pandas.to_timedelta#

pandas.to_timedelta(arg,unit=None,errors='raise')[source]#

Convert argument to timedelta.

Timedeltas are absolute differences in times, expressed in differenceunits (e.g. days, hours, minutes, seconds). This method convertsan argument from a recognized timedelta format / value intoa Timedelta type.

Parameters:

argstr, timedelta, list-like or Series

The data to be converted to timedelta.

Changed in version 2.0:Strings with units ‘M’, ‘Y’ and ‘y’ do not representunambiguous timedelta values and will raise an exception.

unitstr, optional

Denotes the unit of the arg for numericarg. Defaults to"ns".

Possible values:

• ‘W’

• ‘D’ / ‘days’ / ‘day’

• ‘hours’ / ‘hour’ / ‘hr’ / ‘h’ / ‘H’

• ‘m’ / ‘minute’ / ‘min’ / ‘minutes’ / ‘T’

• ‘s’ / ‘seconds’ / ‘sec’ / ‘second’ / ‘S’

• ‘ms’ / ‘milliseconds’ / ‘millisecond’ / ‘milli’ / ‘millis’ / ‘L’

• ‘us’ / ‘microseconds’ / ‘microsecond’ / ‘micro’ / ‘micros’ / ‘U’

• ‘ns’ / ‘nanoseconds’ / ‘nano’ / ‘nanos’ / ‘nanosecond’ / ‘N’

Must not be specified whenarg contains strings anderrors="raise".

Deprecated since version 2.2.0:Units ‘H’, ‘T’, ‘S’, ‘L’, ‘U’ and ‘N’ are deprecated and will be removedin a future version. Please use ‘h’, ‘min’, ‘s’, ‘ms’, ‘us’, and ‘ns’instead of ‘H’, ‘T’, ‘S’, ‘L’, ‘U’ and ‘N’.

errors{‘ignore’, ‘raise’, ‘coerce’}, default ‘raise’

• If ‘raise’, then invalid parsing will raise an exception.

• If ‘coerce’, then invalid parsing will be set as NaT.

• If ‘ignore’, then invalid parsing will return the input.

Returns:

timedelta

If parsing succeeded.Return type depends on input:

• list-like: TimedeltaIndex of timedelta64 dtype

• Series: Series of timedelta64 dtype

• scalar: Timedelta

See also

DataFrame.astype

Cast argument to a specified dtype.

to_datetime

Convert argument to datetime.

convert_dtypes

Convert dtypes.

Notes

If the precision is higher than nanoseconds, the precision of the duration istruncated to nanoseconds for string inputs.

Examples

Parsing a single string to a Timedelta:

>>>pd.to_timedelta('1 days 06:05:01.00003')Timedelta('1 days 06:05:01.000030')>>>pd.to_timedelta('15.5us')Timedelta('0 days 00:00:00.000015500')

Parsing a list or array of strings:

>>>pd.to_timedelta(['1 days 06:05:01.00003','15.5us','nan'])TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015500', NaT],               dtype='timedelta64[ns]', freq=None)

Converting numbers by specifying theunit keyword argument:

>>>pd.to_timedelta(np.arange(5),unit='s')TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',                '0 days 00:00:03', '0 days 00:00:04'],               dtype='timedelta64[ns]', freq=None)>>>pd.to_timedelta(np.arange(5),unit='d')TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],               dtype='timedelta64[ns]', freq=None)