Guide · Open source
How to use luxon: install, parse, format and do date math
Updated · written with AI from the project's own documentation and checked against our catalogue data
Luxon is a JavaScript library for working with dates and times. It gives you DateTime, Duration and Interval types so you can parse, format and calculate with dates in your app. This guide shows you how to install it, how its main pieces fit together and what to check before you rely on it.
Luxonmoment/luxon · ★ 16.5k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install luxon in your project folder.
- 2Import Luxon. Import DateTime, Duration or Interval in the file where you need dates.
- 3Create a DateTime. Use DateTime.now() or another DateTime constructor to get a starting value.
- 4Set the time zone. Use setZone with an IANA zone name such as "America/New_York".
- 5Do date math. Pass a duration object such as { weeks: 1 } to methods like minus.
- 6Format the output. Call toISO() or another formatting method, and check the API docs for options.
Install Luxon with npm
Luxon is installed as a package from npm. Run the command below in your project folder, then import the library in the JavaScript code that needs it.
The README lists no separate prerequisites for installing it.
npm install luxonCreate and read a DateTime
DateTime is the main type in Luxon. It represents a specific point in time, and the README's example starts from DateTime.now(). You can chain methods to change the value, and each call returns a new object because the API is immutable.
- Use DateTime.now() to get the current date and time.
- Chain methods such as setZone, minus and endOf to adjust the value.
- Call toISO() to get the result as an ISO 8601 string.
DateTime.now().setZone("America/New_York").minus({ weeks: 1 }).endOf("day").toISO();Work with time zones
Luxon uses the time zone and Intl support built into the browser or runtime. It does not bundle its own locale or time zone data files. The README's example uses setZone with the name "America/New_York" to move a value into that zone.
Because time zone data comes from the platform, results depend on what the environment supports. If your project cannot rely on that, Luxon is a poor fit.
Do date math with Duration and Interval
Duration represents an amount of time, such as weeks or days. You pass it to methods like minus to shift a date. Interval represents the span between two points in time.
The README's example subtracts a duration of one week using an object: { weeks: 1 }.
- Duration: an amount of time, for example { weeks: 1 } in the README example.
- Interval: the time between two dates or times.
Parse and format dates
Luxon supports parsing and formatting for common formats and for custom formats, according to the README feature list. Check the API docs for the exact methods and format tokens before you use them in production.
If you are switching from Moment.js, the project has a guide for Moment users in its documentation.
- Parsing and formatting common and custom formats is listed as a feature.
- A guide for Moment users is linked from the documentation.
Where to find full documentation
The README links to general documentation, API docs, a quick tour, a Moment users guide, an explanation of why Luxon exists and a quick demo. Start with the quick tour for a first pass and use the API docs as your reference.
- General documentation and the quick tour on the project homepage.
- API docs for every method and type.
- A quick demo page for trying it in the browser.
What people use it for
- Calculating the end of a day in a specific time zone, as in the README example.
- Shifting a stored date back or forward by weeks, days or other units.
- Migrating a codebase from Moment.js using the project's Moment users guide.
- Keeping an app's bundle smaller by relying on platform time zone data instead of shipping locale files.
Frequently asked questions
How do I install Luxon?
Install it from npm with npm install luxon. The README gives this as the install command and lists no other prerequisites.
Is Luxon free to use?
Luxon is released under the MIT licence, as stated in the project's README and listing. Check the LICENSE.md file in the repository for the full text.
Does Luxon need any extra setup for time zones?
Luxon uses the Intl and time zone support of the browser or runtime, and it does not bundle its own time zone data. If the platform does not support what you need, Luxon may not work for your project.
What is the difference between Luxon and Moment.js?
The README says Luxon has a guide for Moment users, which suggests it is designed for teams moving away from Moment.js. Its API is described as immutable and chainable. For a full comparison, read the project's Moment users guide.
What are good alternatives to Luxon?
The comparable projects listed are Moment.js, date-fns, Day.js and the Temporal polyfill. Pick based on your needs, such as whether you rely on platform time zone support.
Can I use Luxon without writing code?
No. Luxon is a code library and must be called from a program. It is not suited to people who only want to display a simple date.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Luxon suits JavaScript developers who need reliable date and time zone handling and want to avoid shipping large locale or time zone data. Teams leaving Moment.js will find a dedicated guide in the docs. If you only need to show a simple date, or your platform cannot provide the Intl and time zone support Luxon depends on, choose a different option.
Install options & downloads