> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/build/work-with-data/handle-special-data-types/work-with-dates-and-times.md). # Work with dates and times [Luxon](https://github.com/moment/luxon/) is a JavaScript library that makes it easier to work with date and time. For full details of how to use Luxon, refer to [Luxon's documentation](https://moment.github.io/luxon/#/?id=luxon). n8n passes dates between nodes as strings, so you need to parse them. Luxon makes this easier. {% hint style="info" %} **Python support** Luxon is a JavaScript library. The two convenience [variables](#get-the-current-datetime-or-date) created by n8n are available when using Python in the Code node, but their functionality is limited: * You can't perform Luxon operations on these variables. For example, there is no Python equivalent for `$today.minus(...)`. * The generic Luxon functionality, such as [Convert date string to Luxon](#convert-date-string-to-luxon), isn't available for Python users. {% endhint %} ## Date and time behavior in n8n Be aware of the following: * In a workflow, n8n converts dates and times to strings between nodes. Keep this in mind when doing arithmetic on dates and times from other nodes. * Using Luxon's `DateTime()` is the recommended approach in n8n. Using vanilla JavaScript's `Date()` doesn't work with some n8n features. For example, it doesn't respect the [Workflow-specific Time Zone](https://docs.n8n.io/workflows/settings/#timezone). * With vanilla JavaScript, you can convert a string to a date with `new Date('2019-06-23')`. In Luxon, you must use a function explicitly stating the format, such as `DateTime.fromISO('2019-06-23')` or `DateTime.fromFormat("23-06-2019", "dd-MM-yyyy")`. ## Setting the timezone in n8n Luxon uses the n8n timezone. This value is either: * Default: `America/New York` * A custom timezone for your n8n instance, set using the `GENERIC_TIMEZONE` environment variable. * A custom timezone for an individual workflow, configured in workflow settings. ## Common tasks This section provides examples for some common operations. More examples, and detailed guidance, are available in [Luxon's own documentation](https://moment.github.io/luxon/#/?id=luxon). ### Get the current datetime or date Use the `$now` and `$today` Luxon objects to get the current time or day: * `now`: a Luxon object containing the current timestamp. Equivalent to `DateTime.now()`. * `today`: a Luxon object containing the current timestamp, rounded down to the day. Equivalent to `DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 })`. Note that these variables can return different time formats when cast as a string: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```javascript {{$now}} // n8n displays the ISO formatted timestamp // For example 2022-03-09T14:02:37.065+00:00 {{"Today's date is " + $now}} // n8n displays "Today's date is " // For example "Today's date is 1646834498755" ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```javascript $now // n8n displays // For example 2022-03-09T14:00:25.058+00:00 let rightNow = "Today's date is " + $now // n8n displays "Today's date is " // For example "Today's date is 1646834498755" ``` {% endtab %} {% tab title="Code node (Python)" %} ```python _now # n8n displays # For example 2022-03-09T14:00:25.058+00:00 rightNow = "Today's date is " + str(_now) # n8n displays "Today's date is " # For example "Today's date is 1646834498755" ``` {% endtab %} {% endtabs %} n8n provides built-in convenience functions to support data transformation in expressions for dates. Refer to [Expression reference](/build/work-with-data/transform-data/expression-reference.md) for more information. ### Convert JavaScript dates to Luxon To convert a native JavaScript date to a Luxon date: * In expressions, use the `.toDateTime()` method. For example, `{{ (new Date()).toDateTime() }}`. * In the Code node, use `DateTime.fromJSDate()`. For example, `let luxondate = DateTime.fromJSDate(new Date())`. ### Convert date string to Luxon You can convert date strings and other date formats to a Luxon DateTime object. You can convert from standard formats and from arbitrary strings. {% hint style="info" %} **A difference between Luxon DateTime and JavaScript Date** With vanilla JavaScript, you can convert a string to a date with `new Date('2019-06-23')`. In Luxon, you must use a function explicitly stating the format, such as `DateTime.fromISO('2019-06-23')` or `DateTime.fromFormat("23-06-2019", "dd-MM-yyyy")`. {% endhint %} #### If you have a date in a supported standard technical format: Most dates use `fromISO()`. This creates a Luxon DateTime from an ISO 8601 string. For example: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{DateTime.fromISO('2019-06-23T00:00:00.00')}} ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let luxonDateTime = DateTime.fromISO('2019-06-23T00:00:00.00') ``` {% endtab %} {% endtabs %} Luxon's API documentation has more information on [fromISO](https://moment.github.io/luxon/api-docs/index.html#datetimefromiso). Luxon provides functions to handle conversions for a range of formats. Refer to Luxon's guide to [Parsing technical formats](https://moment.github.io/luxon/#/parsing?id=parsing-technical-formats) for details. #### If you have a date as a string that doesn't use a standard format: Use Luxon's [Ad-hoc parsing](https://moment.github.io/luxon/#/parsing?id=ad-hoc-parsing). To do this, use the `fromFormat()` function, providing the string and a set of [tokens](https://moment.github.io/luxon/#/parsing?id=table-of-tokens) that describe the format. For example, you have n8n's founding date, 23rd June 2019, formatted as `23-06-2019`. You want to turn this into a Luxon object: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{DateTime.fromFormat("23-06-2019", "dd-MM-yyyy")}} ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let newFormat = DateTime.fromFormat("23-06-2019", "dd-MM-yyyy") ``` {% endtab %} {% endtabs %} When using ad-hoc parsing, note Luxon's warning about [Limitations](https://moment.github.io/luxon/#/parsing?id=limitations). If you see unexpected results, try their [Debugging](https://moment.github.io/luxon/#/parsing?id=debugging) guide. ### Get n days from today Get a number of days before or after today. {% tabs %} {% tab title="Expressions (JavaScript)" %} For example, you want to set a field to always show the date seven days before the current date. In the expressions editor, enter: ```js {{$today.minus({days: 7})}} ``` On the 23rd June 2019, this returns `[Object: "2019-06-16T00:00:00.000+00:00"]`. This example uses n8n's custom variable `$today` for convenience. It's the equivalent of `DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }).minus({days: 7})`. {% endtab %} {% tab title="Code node (JavaScript)" %} For example, you want a variable containing the date seven days before the current date. In the code editor, enter: ```js let sevenDaysAgo = $today.minus({days: 7}) ``` On the 23rd June 2019, this returns `[Object: "2019-06-16T00:00:00.000+00:00"]`. This example uses n8n's custom variable `$today` for convenience. It's the equivalent of `DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }).minus({days: 7})`. {% endtab %} {% endtabs %} For more detailed information and examples, refer to: * Luxon's [guide to math](https://moment.github.io/luxon/#/math) * Their API documentation on [DateTime plus](https://moment.github.io/luxon/api-docs/index.html#datetimeplus) and [DateTime minus](https://moment.github.io/luxon/api-docs/index.html#datetimeminus) ### Create human-readable dates In [Get n days from today](#get-n-days-from-today), the example gets the date seven days before the current date, and returns it as `[Object: "yyyy-mm-dd-T00:00:00.000+00:00"]` (for expressions) or `yyyy-mm-dd-T00:00:00.000+00:00` (in the Code node). To make this more readable, you can use Luxon's formatting functions. For example, you want the field containing the date to be formatted as DD/MM/YYYY, so that on the 23rd June 2019, it returns `23/06/2019`. This expression gets the date seven days before today, and converts it to the DD/MM/YYYY format. {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{$today.minus({days: 7}).toLocaleString()}} ``` {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let readableSevenDaysAgo = $today.minus({days: 7}).toLocaleString() ``` {% endtab %} {% endtabs %} You can alter the format. For example: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{$today.minus({days: 7}).toLocaleString({month: 'long', day: 'numeric', year: 'numeric'})}} ``` On 23rd June 2019, this returns "16 June 2019". {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let readableSevenDaysAgo = $today.minus({days: 7}).toLocaleString({month: 'long', day: 'numeric', year: 'numeric'}) ``` On 23rd June 2019, this returns "16 June 2019". {% endtab %} {% endtabs %} Refer to Luxon's guide on [toLocaleString (strings for humans)](https://moment.github.io/luxon/#/formatting?id=tolocalestring-strings-for-humans) for more information. ### Get the time between two dates To get the time between two dates, use Luxon's diffs feature. This subtracts one date from another and returns a duration. For example, get the number of months between two dates: {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{DateTime.fromISO('2019-06-23').diff(DateTime.fromISO('2019-05-23'), 'months').toObject()}} ``` This returns `[Object: {"months":1}]`. {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let monthsBetweenDates = DateTime.fromISO('2019-06-23').diff(DateTime.fromISO('2019-05-23'), 'months').toObject() ``` This returns `{"months":1}`. {% endtab %} {% endtabs %} Refer to Luxon's [Diffs](https://moment.github.io/luxon/#/math?id=diffs) for more information. ### A longer example: How many days to Christmas? This example brings together several Luxon features, uses JMESPath, and does some basic string manipulation. The scenario: you want a countdown to 25th December. Every day, it should tell you the number of days remaining to Christmas. You don't want to update it for next year - it needs to seamlessly work for every year. {% tabs %} {% tab title="Expressions (JavaScript)" %} ```js {{"There are " + $today.diff(DateTime.fromISO($today.year + '-12-25'), 'days').toObject().days.toString().substring(1) + " days to Christmas!"}} ``` This outputs `"There are days to Christmas!"`. For example, on 9th March, it outputs "There are 291 days to Christmas!". A detailed explanation of what the expression does: * `{{`: indicates the start of the expression. * `"There are "`: a string. * `+`: used to join two strings. * `$today.diff()`: This is similar to the example in [Get the time between two dates](#get-the-time-between-two-dates), but it uses n8n's custom `$today` variable. * `DateTime.fromISO($today.year + '-12-25'), 'days'`: this part gets the current year using `$today.year`, turns it into an ISO string along with the month and date, and then takes the whole ISO string and converts it to a Luxon DateTime data structure. It also tells Luxon that you want the duration in days. * `toObject()` turns the result of diff() into a more usable object. At this point, the expression returns `[Object: {"days":-}]`. For example, on 9th March, `[Object: {"days":-291}]`. * `.days` uses JMESPath syntax to retrieve just the number of days from the object. For more information on using JMESPath with n8n, refer to our [JMESpath](/build/work-with-data/handle-special-data-types/query-json-data.md) documentation. This gives you the number of days to Christmas, as a negative number. * `.toString().substring(1)` turns the number into a string and removes the `-`. * `+ " days to Christmas!"`: another string, with a `+` to join it to the previous string. * `}}`: indicates the end of the expression. {% endtab %} {% tab title="Code node (JavaScript)" %} ```js let daysToChristmas = "There are " + $today.diff(DateTime.fromISO($today.year + '-12-25'), 'days').toObject().days.toString().substring(1) + " days to Christmas!"; ``` This outputs `"There are days to Christmas!"`. For example, on 9th March, it outputs "There are 291 days to Christmas!". A detailed explanation of what the code does: * `"There are "`: a string. * `+`: used to join two strings. * `$today.diff()`: This is similar to the example in [Get the time between two dates](#get-the-time-between-two-dates), but it uses n8n's custom `$today` variable. * `DateTime.fromISO($today.year + '-12-25'), 'days'`: this part gets the current year using `$today.year`, turns it into an ISO string along with the month and date, and then takes the whole ISO string and converts it to a Luxon DateTime data structure. It also tells Luxon that you want the duration in days. * `toObject()` turns the result of diff() into a more usable object. At this point, the expression returns `[Object: {"days":-}]`. For example, on 9th March, `[Object: {"days":-291}]`. * `.days` uses JMESPath syntax to retrieve just the number of days from the object. For more information on using JMESPath with n8n, refer to our [JMESpath](/build/work-with-data/handle-special-data-types/query-json-data.md) documentation. This gives you the number of days to Christmas, as a negative number. * `.toString().substring(1)` turns the number into a string and removes the `-`. * `+ " days to Christmas!"`: another string, with a `+` to join it to the previous string. {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.n8n.io/build/work-with-data/handle-special-data-types/work-with-dates-and-times.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.