xorbits.pandas.to_timedelta(arg: str | float | timedelta, unit: UnitChoices | None = None, errors: DateTimeErrorChoices = 'raise') Timedelta[source]#
xorbits.pandas.to_timedelta(arg: Series, unit: UnitChoices | None = None, errors: DateTimeErrorChoices = 'raise') Series
xorbits.pandas.to_timedelta(arg: list | tuple | range | ArrayLike | Index, unit: UnitChoices | None = None, errors: DateTimeErrorChoices = 'raise') TimedeltaIndex

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.

  • arg (str, timedelta, list-like or Series) –

    The data to be converted to timedelta.

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

  • unit (str, optional) –

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

    Possible values:

    • ’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’

    Must not be specified when arg context strings and errors="raise".

    Deprecated since version 2.1.0(pandas): Units ‘T’ and ‘L’ are deprecated and will be removed in a future version.

  • 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.


If parsing succeeded. Return type depends on input:

  • list-like: TimedeltaIndex of timedelta64 dtype

  • Series: Series of timedelta64 dtype

  • scalar: Timedelta

Return type


See also


Cast argument to a specified dtype.


Convert argument to datetime.


Convert dtypes.


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


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 the unit 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)


This method has not been implemented yet. Xorbits will try to execute it with pandas.

This docstring was copied from pandas.