pandas.to_datetime#

pandas.to_datetime(arg,errors='raise',dayfirst=False,yearfirst=False,utc=False,format=None,exact=<no_default>,unit=None,infer_datetime_format=<no_default>,origin='unix',cache=True)[source]#

Convert argument to datetime.

This function converts a scalar, array-like,Series orDataFrame/dict-like to a pandas datetime object.

Parameters:

argint, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like

The object to convert to a datetime. If aDataFrame is provided, themethod expects minimally the following columns:"year","month","day". The column “year”must be specified in 4-digit format.

errors{‘ignore’, ‘raise’, ‘coerce’}, default ‘raise’

• If'raise', then invalid parsing will raise an exception.

• If'coerce', then invalid parsing will be set asNaT.

• If'ignore', then invalid parsing will return the input.

dayfirstbool, default False

Specify a date parse order ifarg is str or is list-like.IfTrue, parses dates with the day first, e.g."10/11/12"is parsed as2012-11-10.

Warning

dayfirst=True is not strict, but will prefer to parsewith day first.

yearfirstbool, default False

Specify a date parse order ifarg is str or is list-like.

• IfTrue parses dates with the year first, e.g."10/11/12" is parsed as2010-11-12.

• If bothdayfirst andyearfirst areTrue,yearfirst ispreceded (same asdateutil).

Warning

yearfirst=True is not strict, but will prefer to parsewith year first.

utcbool, default False

Control timezone-related parsing, localization and conversion.

• IfTrue, the functionalways returns a timezone-awareUTC-localizedTimestamp,Series orDatetimeIndex. To do this, timezone-naive inputs arelocalized as UTC, while timezone-aware inputs areconverted to UTC.

• IfFalse (default), inputs will not be coerced to UTC.Timezone-naive inputs will remain naive, while timezone-aware oneswill keep their time offsets. Limitations exist for mixedoffsets (typically, daylight savings), seeExamples section for details.

Warning

In a future version of pandas, parsing datetimes with mixed timezones will raise an error unlessutc=True.Please specifyutc=True to opt in to the new behaviourand silence this warning. To create aSeries with mixed offsets andobject dtype, please useapply anddatetime.datetime.strptime.

See also: pandas general documentation abouttimezone conversion andlocalization.

formatstr, default None

The strftime to parse time, e.g."%d/%m/%Y". Seestrftime documentation for more information on choices, thoughnote that"%f" will parse all the way up to nanoseconds.You can also pass:

• “ISO8601”, to parse anyISO8601time string (not necessarily in exactly the same format);

• “mixed”, to infer the format for each element individually. This is risky,and you should probably use it along withdayfirst.

Note

If aDataFrame is passed, thenformat has no effect.

exactbool, default True

Control howformat is used:

• IfTrue, require an exactformat match.

• IfFalse, allow theformat to match anywhere in the targetstring.

Cannot be used alongsideformat='ISO8601' orformat='mixed'.

unitstr, default ‘ns’

The unit of the arg (D,s,ms,us,ns) denote the unit, which is aninteger or float number. This will be based off the origin.Example, withunit='ms' andorigin='unix', this would calculatethe number of milliseconds to the unix epoch start.

infer_datetime_formatbool, default False

IfTrue and noformat is given, attempt to infer the formatof the datetime strings based on the first non-NaN element,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.

Deprecated since version 2.0.0:A strict version of this argument is now the default, passing it hasno effect.

originscalar, default ‘unix’

Define the reference date. The numeric values would be parsed as numberof units (defined byunit) 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 tobeginning of Julian Calendar. Julian day number0 is assignedto the day starting at noon on January 1, 4713 BC.

• If Timestamp convertible (Timestamp, dt.datetime, np.datetimt64 or datestring), origin is set to Timestamp identified by origin.

• If a float or integer, origin is the difference(in units determined by theunit argument) relative to 1970-01-01.

cachebool, default True

IfTrue, use a cache of unique, converted dates to apply thedatetime conversion. May produce significant speed-up when parsingduplicate date strings, especially ones with timezone offsets. The cacheis only used when there are at least 50 values. The presence ofout-of-bounds values will render the cache unusable and may slow downparsing.

Returns:

datetime

If parsing succeeded.Return type depends on input (types in parenthesis correspond tofallback in case of unsuccessful timezone or out-of-range timestampparsing):

• scalar:Timestamp (ordatetime.datetime)

• array-like:DatetimeIndex (orSeries withobject dtype containingdatetime.datetime)

• Series:Series ofdatetime64 dtype (orSeries ofobject dtype containingdatetime.datetime)

• DataFrame:Series ofdatetime64 dtype (orSeries ofobject dtype containingdatetime.datetime)

Raises:

ParserError

When parsing a date from string fails.

ValueError

When another datetime conversion error happens. For example when oneof ‘year’, ‘month’, day’ columns is missing in aDataFrame, orwhen a Timezone-awaredatetime.datetime is found in an array-likeof mixed time offsets, andutc=False.

See also

DataFrame.astype

Cast argument to a specified dtype.

to_timedelta

Convert argument to timedelta.

convert_dtypes

Convert dtypes.

Notes

Many input types are supported, and lead to different output types:

• scalars can be int, float, str, datetime object (from stdlibdatetimemodule ornumpy). They are converted toTimestamp whenpossible, otherwise they are converted todatetime.datetime.None/NaN/null scalars are converted toNaT.

• array-like can contain int, float, str, datetime objects. They areconverted toDatetimeIndex when possible, otherwise they areconverted toIndex withobject dtype, containingdatetime.datetime. None/NaN/null entries are converted toNaT in both cases.

• Series are converted toSeries withdatetime64dtype when possible, otherwise they are converted toSeries withobject dtype, containingdatetime.datetime. None/NaN/nullentries are converted toNaT in both cases.

• DataFrame/dict-like are converted toSeries withdatetime64 dtype. For each row a datetime is created from assemblingthe various dataframe columns. Column keys can be common abbreviationslike [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’, ‘ms’, ‘us’, ‘ns’]) orplurals of the same.

The following causes are responsible fordatetime.datetime objectsbeing returned (possibly inside anIndex or aSeries withobject dtype) instead of a proper pandas designated type(Timestamp,DatetimeIndex orSerieswithdatetime64 dtype):

• when any input element is beforeTimestamp.min or afterTimestamp.max, seetimestamp limitations.

• whenutc=False (default) and the input is an array-like orSeries containing mixed naive/aware datetime, or aware with mixedtime offsets. Note that this happens in the (quite frequent) situation whenthe timezone has a daylight savings policy. In that case you may wish touseutc=True.

Examples

Handling various input formats

Assembling a datetime from multiple columns of aDataFrame. The keyscan be common abbreviations like [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’,‘ms’, ‘us’, ‘ns’]) or plurals of the same

>>>df=pd.DataFrame({'year':[2015,2016],...'month':[2,3],...'day':[4,5]})>>>pd.to_datetime(df)0   2015-02-041   2016-03-05dtype: datetime64[ns]

Using a unix epoch time

>>>pd.to_datetime(1490195805,unit='s')Timestamp('2017-03-22 15:16:45')>>>pd.to_datetime(1490195805433502912,unit='ns')Timestamp('2017-03-22 15:16:45.433502912')

Warning

For float arg, precision rounding might happen. To preventunexpected behavior use a fixed-width exact type.

Using a non-unix epoch origin

>>>pd.to_datetime([1,2,3],unit='D',...origin=pd.Timestamp('1960-01-01'))DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'],              dtype='datetime64[ns]', freq=None)

Differences with strptime behavior

"%f" will parse all the way up to nanoseconds.

>>>pd.to_datetime('2018-10-26 12:00:00.0000000011',...format='%Y-%m-%d %H:%M:%S.%f')Timestamp('2018-10-26 12:00:00.000000001')

Non-convertible date/times

Passingerrors='coerce' will force an out-of-bounds date toNaT,in addition to forcing non-dates (or non-parseable dates) toNaT.

>>>pd.to_datetime('13000101',format='%Y%m%d',errors='coerce')NaT

Timezones and time offsets

The default behaviour (utc=False) is as follows:

• Timezone-naive inputs are converted to timezone-naiveDatetimeIndex:

>>>pd.to_datetime(['2018-10-26 12:00:00','2018-10-26 13:00:15'])DatetimeIndex(['2018-10-26 12:00:00', '2018-10-26 13:00:15'],              dtype='datetime64[ns]', freq=None)

• Timezone-aware inputswith constant time offset are converted totimezone-awareDatetimeIndex:

>>>pd.to_datetime(['2018-10-26 12:00 -0500','2018-10-26 13:00 -0500'])DatetimeIndex(['2018-10-26 12:00:00-05:00', '2018-10-26 13:00:00-05:00'],              dtype='datetime64[ns, UTC-05:00]', freq=None)

• However, timezone-aware inputswith mixed time offsets (for exampleissued from a timezone with daylight savings, such as Europe/Paris)arenot successfully converted to aDatetimeIndex.Parsing datetimes with mixed time zones will show a warning unlessutc=True. If you specifyutc=False the warning below will be shownand a simpleIndex containingdatetime.datetimeobjects will be returned:

>>>pd.to_datetime(['2020-10-25 02:00 +0200',...'2020-10-25 04:00 +0100'])FutureWarning: In a future version of pandas, parsing datetimes with mixedtime zones will raise an error unless `utc=True`. Please specify `utc=True`to opt in to the new behaviour and silence this warning. To create a `Series`with mixed offsets and `object` dtype, please use `apply` and`datetime.datetime.strptime`.Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00],      dtype='object')

• A mix of timezone-aware and timezone-naive inputs is also converted toa simpleIndex containingdatetime.datetime objects:

>>>fromdatetimeimportdatetime>>>pd.to_datetime(["2020-01-01 01:00:00-01:00",...datetime(2020,1,1,3,0)])FutureWarning: In a future version of pandas, parsing datetimes with mixedtime zones will raise an error unless `utc=True`. Please specify `utc=True`to opt in to the new behaviour and silence this warning. To create a `Series`with mixed offsets and `object` dtype, please use `apply` and`datetime.datetime.strptime`.Index([2020-01-01 01:00:00-01:00, 2020-01-01 03:00:00], dtype='object')

Settingutc=True solves most of the above issues:

• Timezone-naive inputs arelocalized as UTC

>>>pd.to_datetime(['2018-10-26 12:00','2018-10-26 13:00'],utc=True)DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 13:00:00+00:00'],              dtype='datetime64[ns, UTC]', freq=None)

• Timezone-aware inputs areconverted to UTC (the output represents theexact same datetime, but viewed from the UTC time offset+00:00).

>>>pd.to_datetime(['2018-10-26 12:00 -0530','2018-10-26 12:00 -0500'],...utc=True)DatetimeIndex(['2018-10-26 17:30:00+00:00', '2018-10-26 17:00:00+00:00'],              dtype='datetime64[ns, UTC]', freq=None)

• Inputs can contain both string or datetime, the aboverules still apply

>>>pd.to_datetime(['2018-10-26 12:00',datetime(2020,1,1,18)],utc=True)DatetimeIndex(['2018-10-26 12:00:00+00:00', '2020-01-01 18:00:00+00:00'],              dtype='datetime64[ns, UTC]', freq=None)