Skip to main content
`Ctrl`+`K`

# pandas.to_timedelta

pandas.to_timedelta(arg, unit=None, errors='raise')

  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:
    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 represent unambiguous timedelta values and will raise an exception.

    unitstr, optional

      Denotes the unit of the arg for numeric arg. 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 when arg contains strings and `errors="raise"`.

      Deprecated since version 2.2.0: Units ‘H’, ‘T’, ‘S’, ‘L’, ‘U’ and ‘N’ are deprecated and will be removed in 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 is truncated 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 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)