Array-based date/time data
Store dates or timestamps in NumPy arrays with a defined temporal resolution.
NumPy · Type Alias
np.datetime64
np.datetime64 is NumPy’s scalar for ISO 8601 dates and date-times. It can also be built from an integer offset from the Unix epoch with an explicit time unit.
- Since
- 1.7
How it works
np.datetime64 is NumPy’s scalar for representing a date or date-time with a selectable unit. Construct it from an ISO 8601 string, or from an integer offset paired with a unit; values derived from integer offsets count from the Unix epoch.
Syntax
numpy.datetime64(value=None, **args)Parameters
| Name | Type | Description |
|---|---|---|
value | str or int, optional | A string in ISO 8601 date or datetime form, or a 64-bit integer offset from the Unix epoch. |
args | unit argument, optional | The datetime unit used with an integer or to request a specific resolution. |
Returns
A NumPy datetime64 scalar.
Key points
- An integer input represents an offset from the Unix epoch.
- String construction accepts ISO 8601 date or date-time representations.
- An integer and unit can create a value with a calendar unit, such as years.
- An integer with day resolution is interpreted relative to the epoch.
Common mistakes
- A trailing timezone in the input string is discarded, and NumPy emits a User Warning.
- Treat datetime64 values as UTC rather than as local-time objects.
Example: Creating datetime64 values
import numpy as np
date = np.datetime64("2024-01-15")
time = np.datetime64("2024-01-15T12:30", "m")
epoch_day = np.datetime64(10, "D")
print(date)
print(time)
print(epoch_day)Creates date-only, minute-resolution, and integer-offset datetime64 values.
When to use it
Epoch-based timestamps
Convert integer epoch offsets into NumPy datetime scalars.
Missing temporal data
Represent missing datetime values using NaT.
Interview questions
QHow can np.datetime64 values be constructed?
Use an ISO 8601 date or datetime string, such as np.datetime64('2005-02-25') or np.datetime64('2005-02-25T03:30'). You can also provide an integer and a unit, such as np.datetime64(1, 'Y'), which represents one year after the Unix epoch.
Follow-up: What happens with a timezone suffix? It is removed during parsing and a User Warning is issued; datetime64 values should be treated as UTC.
QWhat does the integer form mean?
The integer is interpreted as an offset from 1970-01-01T00:00:00, and the second argument selects the unit. For example, np.datetime64(10, 'D') represents ten days after the epoch.
Follow-up: How would you represent a minute-resolution value? Supply a minute unit, for example np.datetime64('2024-01-15T12:30', 'm').
QHow does the unit affect datetime64?
The scalar accepts date units such as years, months, weeks, and days, as well as time units including hours, minutes, seconds, and smaller SI-prefixed units. A string can determine the unit from its ISO 8601 form, or an explicit unit can be supplied.
Follow-up: Why specify a unit explicitly? It makes the intended temporal precision clear and controls how the value is represented.
Related
numpy.timedelta64numpy.datetime_dataDatetimes and timedeltas