pandas.to_timedelta

pandas.to_timedelta(arg, unit='ns', box=True, errors='raise') [source]

Convert argument to timedelta.

Timedeltas are absolute differences in times, expressed in difference units (e.g. days, hours, minutes, seconds). This method converts an argument from a recognized timedelta format / value into a Timedelta type.

Parameters:

arg : str, timedelta, list-like or Series The data to be converted to timedelta. unit : str, default ‘ns’ Denotes the unit of the arg. Possible values: (‘Y’, ‘M’, ‘W’, ‘D’, ‘days’, ‘day’, ‘hours’, hour’, ‘hr’, ‘h’, ‘m’, ‘minute’, ‘min’, ‘minutes’, ‘T’, ‘S’, ‘seconds’, ‘sec’, ‘second’, ‘ms’, ‘milliseconds’, ‘millisecond’, ‘milli’, ‘millis’, ‘L’, ‘us’, ‘microseconds’, ‘microsecond’, ‘micro’, ‘micros’, ‘U’, ‘ns’, ‘nanoseconds’, ‘nano’, ‘nanos’, ‘nanosecond’, ‘N’). box : bool, default True If True returns a Timedelta/TimedeltaIndex of the results. If False returns a numpy.timedelta64 or numpy.darray of values of dtype timedelta64[ns]. Deprecated since version 0.25.0: Use Series.to_numpy() or Timedelta.to_timedelta64() instead to get an ndarray of values or numpy.timedelta64, respectively. 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:

timedelta64 or numpy.array of timedelta64 Output type returned if parsing succeeded.

See also

DataFrame.astype

Cast argument to a specified dtype.

to_datetime

Convert argument to datetime.

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.000015')

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.000015', NaT],
               dtype='timedelta64[ns]', freq=None)

Converting numbers by specifying the unit keyword argument:

>>> pd.to_timedelta(np.arange(5), unit='s')
TimedeltaIndex(['00:00:00', '00:00:01', '00:00:02',
                '00:00:03', '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)

Returning an ndarray by using the ‘box’ keyword argument:

>>> pd.to_timedelta(np.arange(5), box=False)
array([0, 1, 2, 3, 4], dtype='timedelta64[ns]')