Skip to content


You can specify a CLI parameter as a Python datetime.

Your function will receive a standard Python datetime object, and again, your editor will give you completion, etc.

from datetime import datetime

import typer

def main(birth: datetime):
    typer.echo(f"Interesting day to be born: {birth}")
    typer.echo(f"Birth hour: {birth.hour}")

if __name__ == "__main__":

Typer will accept any string from the following formats: * %Y-%m-%d * %Y-%m-%dT%H:%M:%S * %Y-%m%d %H:%M:%S

Check it:

$ python --help

Usage: [OPTIONS] BIRTH:[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]

  BIRTH:[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S][required]

  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  --help                Show this message and exit.

// Pass a datetime
$ python 1956-01-31T10:00:00

Interesting day to be born: 1956-01-31 10:00:00
Birth hour: 10

// An invalid date
$ python july-19-1989

Usage: [OPTIONS] [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d%H:%M:%S]

Error: Invalid value for '[%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]': invalid datetime format: july-19-1989. (choose from %Y-%m-%d, %Y-%m-%dT%H:%M:%S, %Y-%m-%d %H:%M:%S)

Custom date format

You can also customize the formats received for the datetime with the formats parameter.

formats receives a list of strings with the date formats that would be passed to datetime.strptime().

For example, let's imagine that you want to accept an ISO formatted datetime, but for some strange reason, you also want to accept a format with:

  • first the month
  • then the day
  • then the year
  • separated with "/"

...It's a crazy example, but let's say you also needed that strange format:

from datetime import datetime

import typer

def main(
    launch_date: datetime = typer.Argument(
        ..., formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%m/%d/%Y"]
    typer.echo(f"Launch will be at: {launch_date}")

if __name__ == "__main__":


Notice the last string in formats: "%m/%d/%Y".

Check it:

// ISO dates work
$ python 1969-10-29

Launch will be at: 1969-10-29 00:00:00

// But the strange custom format also works
$ python 10/29/1969

Launch will be at: 1969-10-29 00:00:00