datetime2 package FAQ

This is the FAQ for the datetime2 package. See also the datetime2 package documentation.

The datetime2 package uses the tracklang package to detect document languages. Related: tracklang package and Localisation with tracklang.tex.

General
Unexpected Output
Localisation
Date/Time Styles

General

Why was a new package made instead of updating datetime.sty? 🔗

This is discussed in the datetime2 documentation but briefly there were issues with datetime.sty that couldn’t be resolved without substantially breaking backward-compatibility.

2020-07-03 12:22:23

Top

Can I still use the old datetime package? 🔗

Obsolete packages remain available in the CTAN obsolete tree. Your TeX distribution may not contain some obsolete packages. If this is the case, you will need to download datetime.sty from CTAN and manually install.

It’s your choice if you want to continue to use an obsolete package, but you should be aware that any issues with unmaintained packages won’t be fixed.

2023-04-14 10:12:27

Top

What are the main differences between datetime and datetime2? 🔗

The main changes are:

All commands except \today and \Today have a prefix to help prevent clashes with other date and time-related packages. For example, \DTMcurrenttime instead of \currenttime.
Commands like \today are designed to be expandable, which means you should be able to use them to write the date/time information to external files, use them in PDF bookmarks or metadata or use them in commands like \MakeUppercase. Styles should protect any fragile commands to assist with this. There may, however, be some supplementary styles in contributed packages that can’t produce expandable dates or styles. In which case this should be mentioned in the documentation for those supplementary packages.
Language support is separated into independently installed and maintained modules. This means you only need to install the modules for your own language(s) rather than having to install everything. It also means that the language support can be maintained by someone who is actually familiar with the language.

2023-04-14 10:15:13

Top

How do I change my document from datetime.sty? 🔗

The default date format in datetime2.sty has changed to ISO so if your old document looked like:

\documentclass{article}
\usepackage{datetime}
\begin{document}
\today
\end{document}

then the date would be formatted in British English style: Saturday 28^th March, 2015. If you simply replace datetime with datetime2:

\documentclass{article}
\usepackage{datetime2}
\begin{document}
\today
\end{document}

then the date would be formatted in ISO style: 2015-03-28. If you want to reproduce the British format you need to make sure you have also installed datetime2-english and load it using package options:

\documentclass{article}
\usepackage[en-GB,showdow]{datetime2}
\begin{document}
\today
\end{document}

This now displays the date in the style Saturday 28th March 2015, which is slightly different from the datetime.sty format. You can also use british instead of en-GB, but take care if you try loading it as a document class option. If you try

\documentclass[british]{article}
\usepackage[showdow]{datetime2}
\begin{document}
\today
\end{document}

this once again produces the ISO format 2015-03-28 but you can now switch to the British style using \DTMsetstyle{en-GB} or do

\documentclass[british]{article}
\usepackage[useregional,showdow]{datetime2}
\begin{document}
\today
\end{document}

Similarly if you use babel:

\documentclass[british]{article}
\usepackage{babel}
\usepackage[useregional,showdow]{datetime2}
\begin{document}
\today
\end{document}

If you want the suffix as a superscript you need to add

\DTMlangsetup[en-GB]{ord=raise}

before you display the date. If you additionally want the comma you need to do:

\DTMlangsetup[en-GB]{ord=raise,monthyearsep={,\space}}

datetime2.sty uses different command names to datetime.sty (except for \today) and prefixes them all to prevent clashes with other packages. It also uses an ISO year month day way of specifying dates in command arguments to avoid confusion. For example

\formatdate{28}{3}{2014}% datetime.sty

needs to be replaced with

\DTMdisplaydate{2014}{3}{28}{-1}% datetime2.sty

\DTMdate{2014-3-28}% datetime2.sty

Note that \DTMdate isn’t expandable (but can calculate the week day, if enabled) whereas \DTMdisplaydate is expandable (but can’t calculate the week day).

Saving dates has similarly changed from:

\newdate{mydate}{28}{3}{2015}% datetime.sty

\DTMsavedate{mydate}{2015-03-28}% datetime2.sty

Using the dates has changed from:

\displaydate{mydate}% datetime.sty

\DTMusedate{mydate}% datetime2.sty

2023-04-14 10:16:36

Top

Unexpected Output

The day of week doesn’t show when I use showdow 🔗

Not all styles, including some of the language styles, implement the showdow option. Check with the documentation for the relevant package or language module.

2020-07-03 13:11:28

Top

Unwanted space occurs after language change 🔗

Update 2019-10-28: I’ve fixed all unmaintained modules.

This is a known bug. Unfortunately the template used to create all the language .ldf files had an uncommented end of line character. I've fixed this in datetime2-english and am working my way through all the modules, fixing the unmaintained ones and contacting the new maintainers of the ones that have been adopted. Unfortunately, due to the large number of modules this is quite time-consuming, so please be patient. If you would like to take over maintenance of any of the unadopted modules, please contact me so that I can notify the CTAN team. In the mean time, if you are experiencing this problem, here’s a fix until the new version is available: modify the appropriate date command \datelanguage to switch the date style. For example:

\documentclass{article}

\usepackage{polyglossia}
\setmainlanguage{french}
\usepackage[useregional]{datetime2}

\renewcommand\datefrench{%
  \DTMifcaseregional
  {}% do nothing
  {\DTMsetstyle{french}}%
  {\DTMsetstyle{french-numeric}}%
}

\begin{document}

``\textfrench{\today}''

\end{document}

2020-07-03 13:12:34

Top

datetime2 doesn’t recognise babel’s \babelprovide 🔗

Unfortunately babel doesn’t currently provide a list of languages that have been loaded with \babelprovide, there’s no way for tracklang (or any other package) to simply access that information. Related: Localisation with tracklang.tex.

2020-07-03 13:16:13

Top

The time zone is incorrect 🔗

The datetime2 package obtains the date, time and time zone information in different ways, depending on the TeX engine:

If \pdfcreationdate is defined (PDFLaTeX or LuaLaTeX with the luatex85 package) the information is obtained by parsing the output produced by the command;
if \pdffeedback is defined (LuaLaTeX) the equivalent is performed with \pdffeedback creationdate.
Old versions of XeLaTeX don’t provide either of those commands, so the information is obtained as follows:
- if \LocaleNowStamp (provided by the tex-locale package) is defined the expansion of that will be used;
- if \TeXOSQueryNow (provided by texosquery) is defined then that will be used;
- if all the above fail, then the date and time are obtained from the TeX primitives \day, \month, \year and \time, which give the day, month, year, hours and minutes but not seconds or time zone.

XeLaTeX now provides \creationdate. The next version of datetime2 will add support for this. In the meantime, if you are using a new version of XeLaTeX, add the following line before you load datetime2:

\providecommand{\pdfcreationdate}{\creationdate}

If you’re not using XeLaTeX and the time zone is incorrect, then check the output of \pdfcreationdate or (if LuaLaTeX) \pdffeedback creationdate. If the time zone is incorrect in that output then the problem is that the TeX distribution that you are using is picking up a time zone that you weren’t expecting.

If TeX is installed on your local device, check your time settings. If TeX is installed on a remote server (for example, if you are using Overleaf) then it’s using the remote server’s time zone. If you are using latexmk (as with Overleaf), you can change the time zone environment variable, that is, the TZ variable used in POSIX systems. If you are not using latexmk then there are other ways of setting the TZ variable before you run a command. If you are not using a POSIX system then you will need to find out the appropriate equivalent setting or follow the XeLaTeX advice below.

If you are using XeLaTeX and can’t switch to a different engine, and you need the time zone, but you are unable to use texosquery either because the shell escape is completely disabled or your system doesn’t support Java applications then you will need to set up a build system that incorporates a way of saving the information that can be picked up by TeX. This depends on your operating system. (Note that changing the TZ environment variable doesn’t help in this case, as XeLaTeX doesn’t use that information.)

If you can use the texosquery application outside of TeX (that is, your system supports Java applications but TeX has the shell escape disabled) then you can use texosquery outside of TeX with the output saved to a temporary file and input the result. For example, run the following before running XeLaTeX:

texosquery -n > currentdate.tex

and include the following lines in your XeLaTeX document:

\usepackage{texosquery}
\TeXOSQueryFromFile{\pdfcreationdate}{currentdate}

This will define \pdfcreationdate regardless of whether or not you use datetime2 (but if you are using datetime2 make sure you set \pdfcreationdate before loading datetime2). Note that the texosquery application uses special markup in its output, so you can’t simply \input the file.

If you can’t use Java (for example, if you are using Overleaf) then you will need to find some other way of creating that temporary file. You can still use the above texosquery.sty code even if the file wasn’t created by the texosquery application, as long as the file contents has the correct format (which should match the format of \pdfcreationdate). I can’t help you with this. You will have to ask for help in a forum or other help channel applicable to your operating system.

2023-08-28 14:42:14

Top

Localisation

Why doesn’t datetime2 recognise my language? 🔗

The language and regional settings are dealt with by the datetime2 modules, which must be independently installed. Check the datetime2-contrib listings. If your language is listed there you can install it. If it’s not listed there, the appropriate language module is unavailable, in which case you have the following options: volunteer to write the module or persuade someone to write the module.

See also Writing a datetime2 Language Module and section 6 “Multi-Lingual Support” in the datetime2 documentation.

2023-04-14 10:05:09

Top

Why is showdow a package option rather than a language option? 🔗

In order to show the day of week (showdow=true), the week day needs to be calculated for commands like \today and \DTMdate. This requires that the datetime2-calc.sty package is loaded. If showdow is used as a package option, it can automatically load datetime2-calc after datetime2 has finished loading, which saves you from remembering to load it. Since the datetime2-calc package additionally requires pgfkeys and pgfcalendar which adds to the overall document build time, it’s not loaded unless required.

2021-09-29 10:30:45

Top

How do I make the date appear in my regional format instead of the default ISO format? 🔗

First, you need to make sure that you have the relevant datetime2 language module installed. For example, to display the date in the en-GB style (British English) you need to install the datetime2-english module using your TeX package manager. (This needs to be done in addition to installing datetime2.)

Next you need to ensure that datetime2 picks up the correct locale setting for your document. Unfortunately, this doesn’t always work (see Localisation with tracklang.tex).

You can explicitly set the locale in the datetime2 package option list. For example:

\usepackage[en-GB]{datetime2}

If the language has been loaded before datetime2 then you need to explicitly switch on regional support. For example:

\documentclass[british]{article}
\usepackage{babel}
\usepackage[useregional]{datetime2}

If you prefer a numeric regional style then you need useregional=numeric.

Each style comes with its own set of options that are relevant to the particular style. These should be set using \DTMlangsetup. For example:

\documentclass{article}
\usepackage[en-GB,en-US]{datetime2}

\DTMlangsetup[en-GB]{ord=raise,abbr,monthyearsep={,\space}}
\DTMlangsetup[en-US]{dayyearsep={,\space}}

\begin{document}
GB date: \DTMsetstyle{en-GB}\DTMdate{2021-06-31}.

US date: \DTMsetstyle{en-US}\DTMdate{2021-06-31}.
\end{document}

This produces:

GB date: 31^st Jun, 2021.
US date: June 31, 2021.

2021-05-08 22:01:45

Top

How do I modify a regional date style? 🔗

You can use the options that are provided by the style for minor modifications, such as the example given in How do I make the date appear in my regional format instead of the default ISO format? If you have a more significant change that can’t be obtained through the style options, then you can define your own style.

For example, suppose you want the date in the form 2021-Aug-01. This has the year at the start but it uses an abbreviated English month name and a two-digit day. This format can’t be obtained with any of the styles provided by datetime2-english, so a new style is needed.

First you need to make sure that the English month name commands are provided, so you need to load datetime2 with en (the ISO language code for English), but you don’t want to switch to that style so you also need useregional=false:

\usepackage[en,useregional=false]{datetime2}

Now you can define a style that uses the English commands:

\DTMnewdatestyle
 {yyyyMonthdd}% label
 {% style commands
   \renewcommand{\DTMdisplaydate}[4]{%
      \number##1 % year
      -% separator
      \DTMenglishshortmonthname{##2}% abbreviated month
      -% separator
      \DTMtwodigits{##3}% two-digit day
   }%
   \renewcommand{\DTMDisplaydate}[4]{%
      \DTMdisplaydate{##4}{##3}{##2}{##1}%
   }%
 }

Remember that you need to set the style once it’s defined:

\DTMsetdatestyle{yyyyMonthdd}

2023-04-14 10:07:16

Top

How do I write a datetime2 language module? 🔗

The datetime2 package uses the tracklang package to detect the document languages, so I recommend you read Localisation with tracklang.tex first and then Writing a datetime2 Language Module.

2021-09-29 10:26:04

Top

How do I provide for different declension (nominative, genitive etc)?) 🔗

Provide separate commands for each declension. An example is given in this TeX.SE answer for Czech, which defines \DTMczechnominativemonthname for the nominative case, and \DTMczechgenitivemonthname for the genitive case. The command \DTMczechmonthname needs to be initialised to the most appropriate of these. For example,

\newcommand*{\DTMczechmonthname}{\DTMczechgenitivemonthname}

Remember that if support for multiple file encodings is needed, an ASCII version needs to be defined in the -ascii.ldf file and the UTF-8 version needs to be defined in the -utf8.ldf file.

You can then provide a key for use with the language module to allow users to switch forms. For example:

\DTMdefchoicekey{czech}{month}[\val\nr]{genitive,nominative}{%
 \ifcase\nr\relax
  \renewcommand*\DTMczechmonthname{\DTMczechgenitivemonthname}%
  \renewcommand*\DTMczechMonthname{\DTMczechgenitiveMonthname}%
 \or
  \renewcommand*\DTMczechmonthname{\DTMczechnominativemonthname}%
  \renewcommand*\DTMczechMonthname{\DTMczechnominativeMonthname}%
 \fi
}

Similarly for week day names, if supported.

2023-04-14 10:10:40

Top

Date/Time Styles

Is there an equivalent to datetime’s \textdate and \oclock styles? 🔗

Yes, but you need to load the datetime2-en-fulltext package. Example usage:

\documentclass{article}
\usepackage[showdow]{datetime2-en-fulltext}
\begin{document}
Date: \today. Time: \DTMcurrenttime.
\end{document}

See the datetime2-en-fulltext documentation for further details.

2023-04-14 10:31:46

Top

I’ve written a new date/time style. How can I share it? 🔗

Put it in a package and upload it to CTAN. (Make sure you first read CTAN’s upload guide.) For the suggested CTAN directory use /macros/latex/contrib/datetime2-contrib/package-name where package-name is the name of your package. See also the end of section 5.2 “Defining New Styles” in the datetime2 manual.

2023-04-14 10:32:20

Top

How do I add a test for the showdow setting to a style? 🔗

You can use the \ifDTMshowdow conditional to determine the showdow setting, but remember that the style should also check if the day of week index has been set to -1 (which indicates that the day of week name should be ignored for a specific use case). So when you redefine \DTMdisplaydate within \DTMnewstyle or \DTMnewdatestyle the test for the day of week name should look something like:

 \ifDTMshowdow
   \ifnum##4>-1 % space needed after -1
     % code that inserts the day of week name
     % where the day of week index is given by ##4
   \fi
 \fi

If you are writing a language module, you need to define \DTMlangweekdayname where lang is the root language label. For example, datetime2-english defines \DTMenglishweekdayname. This naming scheme is needed in order to work with \DTMweekdayname provided by datetime2-calc.sty. (Similarly define \DTMlangWeekdayname for first letter upper case version, \DTMlangshortweekdayname and \DTMlangshortWeekdayname for abbreviated versions, if required.)

If the week or month names include non-ASCII characters, there should be an ASCII version of \DTMlangweekdayname in the file datetime2-lang-ascii.ldf and a UTF-8 version in the file datetime2-lang-utf8.ldf. You might find it easiest to adapt the code from an existing language module. For example, datetime2-french.dtx. This will allow support for multiple file encodings.

You might also want to consider providing a command to use as the separator between the day of week name and the rest of the date. For example, datetime2-en-GB.ldf defines:

\newcommand*{\DTMenGBdowdaysep}{\space}

and also provides a key to change this value with \DTMlangsetup[en-GB]{dowdaysep={separator code}}:

\DTMdefkey{en-GB}{dowdaysep}{\renewcommand*{\DTMenGBdowdaysep}{#1}}

Another example is with datetime2-romanian which is regionless, so datetime2-romanian.ldf provides:

\newcommand*{\DTMromaniandowdaysep}{\space}

and

\DTMdefkey{romanian}{dowdaysep}{\renewcommand*{\DTMromaniandowdaysep}{#1}}

2023-04-14 10:34:05

Top

How do I temporarily change the date/time style? 🔗

Command like \DTMsetstyle are local to the current scope, so you can just put them inside a group. For example:

{\DTMsetstyle{ddmmyyyy}\DTMnow}

2021-09-29 10:32:57

Top