Skip to main content
`Ctrl`+`K`

# pandas.Timedelta

class pandas.Timedelta(value=<object object>, unit=None, **kwargs)

  Represents a duration, the difference between two dates or times.

  Timedelta is the pandas equivalent of python’s `datetime.timedelta` and is interchangeable with it in most cases.

  Parameters:
    value Timedelta, timedelta, np.timedelta64, str, int or float

      Input value.

    unit str, default ‘ns’

      If input is an integer, denote the unit of the input. If input is a float, denote the unit of the integer parts. The decimal parts with resolution lower than 1 nanosecond are ignored.

      Possible values:

      - ‘W’, or ‘D’

      - ‘days’, or ‘day’

      - ‘hours’, ‘hour’, ‘hr’, or ‘h’

      - ‘minutes’, ‘minute’, ‘min’, or ‘m’

      - ‘seconds’, ‘second’, ‘sec’, or ‘s’

      - ‘milliseconds’, ‘millisecond’, ‘millis’, ‘milli’, or ‘ms’

      - ‘microseconds’, ‘microsecond’, ‘micros’, ‘micro’, or ‘us’

      - ‘nanoseconds’, ‘nanosecond’, ‘nanos’, ‘nano’, or ‘ns’.

      Deprecated since version 3.0.0: Allowing the values w, d, MIN, MS, US and NS to denote units are deprecated in favour of the values W, D, min, ms, us and ns.

    **kwargs

      Available kwargs: {days, seconds, microseconds, milliseconds, minutes, hours, weeks}. Values for construction in compat with datetime.timedelta. Numpy ints and floats will be coerced to python ints and floats.

  See also

  `Timestamp`

    Represents a single timestamp in time.

  `TimedeltaIndex`

    Immutable Index of timedelta64 data.

  `DateOffset`

    Standard kind of date increment used for a date range.

  `to_timedelta`

    Convert argument to timedelta.

  `datetime.timedelta`

    Represents a duration in the datetime module.

  `numpy.timedelta64`

    Represents a duration compatible with NumPy.

  Notes

  The constructor may take in either both values of value and unit or kwargs as above. Either one of them must be used during initialization

  The `.value` attribute is always in ns.

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

  Examples

  Here we initialize Timedelta object with both value and unit

      >>> td = pd.Timedelta(1, "D")
      >>> td
      Timedelta('1 days 00:00:00')

  Here we initialize the Timedelta object with kwargs

      >>> td2 = pd.Timedelta(days=1)
      >>> td2
      Timedelta('1 days 00:00:00')

  We see that either way we get the same result

  Attributes

  `asm8` | Return a numpy timedelta64 array scalar view.
  `components` | Return a components namedtuple-like.
  `days` | Returns the days of the timedelta.
  `max` |
  `microseconds` | Return the number of microseconds (n), where 0 <= n < 1 millisecond.
  `min` |
  `nanoseconds` | Return the number of nanoseconds (n), where 0 <= n < 1 microsecond.
  `resolution` |
  `resolution_string` | Return a string representing the lowest timedelta resolution.
  `seconds` | Return the total hours, minutes, and seconds of the timedelta as seconds.
  `unit` | Return the unit of Timedelta object.
  `value` | Return the value of Timedelta object in nanoseconds.

  Methods

  `as_unit`(unit[, round_ok]) | Convert the underlying int64 representation to the given unit.
  `ceil`(freq) | Return a new Timedelta ceiled to this resolution.
  `floor`(freq) | Return a new Timedelta floored to this resolution.
  `isoformat`() | Format the Timedelta as ISO 8601 Duration.
  `round`(freq) | Round the Timedelta to the specified resolution.
  `to_numpy`([dtype, copy]) | Convert the Timedelta to a NumPy timedelta64.
  `to_pytimedelta`() | Convert a pandas Timedelta object into a python `datetime.timedelta` object.
  `to_timedelta64`() | Return a numpy.timedelta64 object with 'ns' precision.
  `total_seconds`() | Total seconds in the duration.
  `view`(dtype) | Array view compatibility.