w3resource

Pandas: Data Manipulation - to_datetime() function

to_datetime() function

The to_datetime() function is used to convert argument to datetime.

Syntax:

pandas.to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc=None, format=None, exact=True, unit=None, infer_datetime_format=False, origin='unix', cache=True)

Parameters:

Name Description Type / Default Value Required / Optional
arg scalar, list, tuple, 1-d array, or Series Required
errors
  • If 'raise', then invalid parsing will raise an exception
  • If 'coerce', then invalid parsing will be set as NaN
  • If 'ignore', then invalid parsing will return the input
{'ignore', 'raise', 'coerce'},
Default Value: 'raise'
Optional
dayfirst Specify a date parse order if arg is str or its list-likes. If True, parses dates with the day first, eg 10/11/12 is parsed as 2012-11-10. Warning: dayfirst=True is not strict, but will prefer to parse with day first (this is a known bug, based on dateutil behavior). boolean
Default Value: False
Optional
yearfirst Specify a date parse order if arg is str or its list-likes.
  • If True parses dates with the year first, eg 10/11/12 is parsed as 2010-11-12.
  • If both dayfirst and yearfirst are True, yearfirst is preceded (same as dateutil).
Warning: yearfirst=True is not strict, but will prefer to parse with year first (this is a known bug, based on dateutil behavior).
boolean
Default Value: False
Optional
utc Return UTC DatetimeIndex if True (converting any tz-aware datetime.datetime objects as well). boolean
Default Value: None
Optional
format trftime to parse time, eg “%d/%m/%Y”, note that “%f” will parse all the way up to nanoseconds. See strftime documentation for more information on choices: string
Default Value: None
Required
exact
  • If True, require an exact format match.
  • If False, allow the format to match anywhere in the target string.
boolean
Default Value: True
Required
unit unit of the arg (D,s,ms,us,ns) denote the unit, which is an integer or float number. This will be based off the origin. Example, with unit=’ms’ and origin=’unix’ (the default), this would calculate the number of milliseconds to the unix epoch start string
Default Value: 'ns'
Required
infer_datetime_format If True and no format is given, attempt to infer the format of the datetime strings, and if it can be inferred, switch to a faster method of parsing them. In some cases this can increase the parsing speed by ~5-10x. boolean
Default Value: False
Required
origin Define the reference date. The numeric values would be parsed as number of units (defined by unit) since this reference date.
  • If 'unix' (or POSIX) time; origin is set to 1970-01-01.
  • If 'julian', unit must be 'D', and origin is set to beginning of Julian Calendar. Julian day number 0 is assigned to the day starting at noon on January 1, 4713 BC.
  • If Timestamp convertible, origin is set to Timestamp identified by origin.
scalar
Default Value: 'unix'
Required
cache If True, use a cache of unique, converted dates to apply the datetime conversion. May produce significant speed-up when parsing duplicate date strings, especially ones with timezone offsets. boolean
Default Value: True
Required

Returns: datetime if parsing succeeded.
Return type depends on input:

  • list-like: DatetimeIndex
  • Series: Series of datetime64 dtype
  • scalar: Timestamp

Example:


Download the above Notebook from here.

Previous: to_numeric() function
Next: to_timedelta() function