# pandas.to_timedelta

`pandas.``to_timedelta`(arg, unit='ns', box=True, 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:

  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]')

Scroll To Top