dateparser – python parser for human readable dates — DateParser 1.4.2 documentation

# dateparser – python parser for human readable dates

Key Features • How To Use • Installation • Common use cases • You may also like... • License

## Key Features

- Support for almost every existing date format: absolute dates, relative dates (`"two weeks ago"` or `"tomorrow"`), timestamps, etc.

- Support for more than 200 language locales.

- Language autodetection

- Customizable behavior through settings.

- Support for non-Gregorian calendar systems.

- Support for dates with timezones abbreviations or UTC offsets (`"August 14, 2015 EST"`, `"21 July 2013 10:15 pm +0500"`…)

- Search dates in longer texts.

- Time span detection for expressions like “past month”, “last week”.

## Online demo

Do you want to try it out without installing any dependency? Now you can test it quickly by visiting this online demo!

## How To Use

The most straightforward way to parse dates with dateparser is to use the `dateparser.parse()` function, that wraps around most of the functionality of the module.

    >>> import dateparser

    >>> dateparser.parse('Fri, 12 Dec 2014 10:55:50')
    datetime.datetime(2014, 12, 12, 10, 55, 50)

    >>> dateparser.parse('1991-05-17')
    datetime.datetime(1991, 5, 17, 0, 0)

    >>> dateparser.parse('In two months')  # today is 1st Aug 2020
    datetime.datetime(2020, 10, 1, 11, 12, 27, 764201)

    >>> dateparser.parse('1484823450')  # timestamp
    datetime.datetime(2017, 1, 19, 10, 57, 30)

    >>> dateparser.parse('January 12, 2012 10:00 PM EST')
    datetime.datetime(2012, 1, 12, 22, 0, tzinfo=<StaticTzInfo 'EST'>)

dateparser also works with strings in different languages:

    >>> dateparser.parse('Martes 21 de Octubre de 2014')  # Spanish (Tuesday 21 October 2014)
    datetime.datetime(2014, 10, 21, 0, 0)

    >>> dateparser.parse('Le 11 Décembre 2014 à 09:00')  # French (11 December 2014 at 09:00)
    datetime.datetime(2014, 12, 11, 9, 0)

    >>> dateparser.parse('13 января 2015 г. в 13:34')  # Russian (13 January 2015 at 13:34)
    datetime.datetime(2015, 1, 13, 13, 34)

    >>> dateparser.parse('1 เดือนตุลาคม 2005, 1:00 AM')  # Thai (1 October 2005, 1:00 AM)
    datetime.datetime(2005, 10, 1, 1, 0)

    >>> dateparser.parse('yaklaşık 23 saat önce')  # Turkish (23 hours ago), current time: 12:46
    datetime.datetime(2019, 9, 7, 13, 46)

    >>> dateparser.parse('2小时前')  # Chinese (2 hours ago), current time: 22:30
    datetime.datetime(2018, 5, 31, 20, 30)

You can specify the language(s), if known, using the `languages` argument. In this case, given languages are used and language detection is skipped:

    >>> dateparser.parse('2015, Ago 15, 1:08 pm', languages=['pt', 'es'])
    datetime.datetime(2015, 8, 15, 13, 8)

If you know the possible formats of the dates, you can use the `date_formats` argument:

    >>> dateparser.parse('22 Décembre 2010', date_formats=['%d %B %Y'])
    datetime.datetime(2010, 12, 22, 0, 0)

### Relative Dates

    >>> from dateparser import parse
    >>> parse('1 hour ago')
    datetime.datetime(2015, 5, 31, 23, 0)
    >>> parse('Il ya 2 heures')  # French (2 hours ago)
    datetime.datetime(2015, 5, 31, 22, 0)
    >>> parse('1 anno 2 mesi')  # Italian (1 year 2 months)
    datetime.datetime(2014, 4, 1, 0, 0)
    >>> parse('yaklaşık 23 saat önce')  # Turkish (23 hours ago)
    datetime.datetime(2015, 5, 31, 1, 0)
    >>> parse('Hace una semana')  # Spanish (a week ago)
    datetime.datetime(2015, 5, 25, 0, 0)
    >>> parse('2小时前')  # Chinese (2 hours ago)
    datetime.datetime(2015, 5, 31, 22, 0)

Note

Testing above code might return different values depending on your environment’s current date and time.

Note

For the `Finnish` language, please specify `settings={'SKIP_TOKENS': []}` to correctly parse relative dates.

### Date Order

    >>> # parsing ambiguous date
    >>> parse('02-03-2016')  # assumes english language, uses MDY date order
    datetime.datetime(2016, 2, 3, 0, 0)
    >>> parse('le 02-03-2016')  # detects french, uses DMY date order
    datetime.datetime(2016, 3, 2, 0, 0)

Note

Ordering is not locale-based — do not expect `DMY` order for UK/Australia English. You can specify date order explicitly:

    >>> parse('18-12-15 06:00', settings={'DATE_ORDER': 'DMY'})
    datetime.datetime(2015, 12, 18, 6, 0)

For more on date order, see the settings documentation.

### Timezone and UTC Offset

By default, dateparser returns a timezone-aware `datetime` if a timezone is present in the date string. Otherwise it returns a naive `datetime` object.

    >>> parse('January 12, 2012 10:00 PM EST')
    datetime.datetime(2012, 1, 12, 22, 0, tzinfo=<StaticTzInfo 'EST'>)

    >>> parse('January 12, 2012 10:00 PM -0500')
    datetime.datetime(2012, 1, 12, 22, 0, tzinfo=<StaticTzInfo 'UTC\-05:00'>)

    >>> parse('2 hours ago EST')
    datetime.datetime(2017, 3, 10, 15, 55, 39, 579667, tzinfo=<StaticTzInfo 'EST'>)

If the date has no timezone name/abbreviation or offset, you can specify it using the `TIMEZONE` setting:

    >>> parse('January 12, 2012 10:00 PM', settings={'TIMEZONE': 'US/Eastern'})
    datetime.datetime(2012, 1, 12, 22, 0)

    >>> parse('January 12, 2012 10:00 PM', settings={'TIMEZONE': 'US/Eastern', 'RETURN_AS_TIMEZONE_AWARE': True})
    datetime.datetime(2012, 1, 12, 22, 0, tzinfo=<DstTzInfo 'US/Eastern' EST-1 day, 19:00:00 STD>)

    >>> parse('10:00 am', settings={'TIMEZONE': 'EST', 'TO_TIMEZONE': 'EDT'})
    datetime.datetime(2016, 9, 25, 11, 0)

    >>> parse('10:00 am EST', settings={'TO_TIMEZONE': 'EDT'})
    datetime.datetime(2017, 3, 12, 11, 0, tzinfo=<StaticTzInfo 'EDT'>)

For more on timezones, see the settings documentation.

### Incomplete Dates

    >>> from dateparser import parse
    >>> parse('December 2015')  # default behavior
    datetime.datetime(2015, 12, 16, 0, 0)
    >>> parse('December 2015', settings={'PREFER_DAY_OF_MONTH': 'last'})
    datetime.datetime(2015, 12, 31, 0, 0)
    >>> parse('December 2015', settings={'PREFER_DAY_OF_MONTH': 'first'})
    datetime.datetime(2015, 12, 1, 0, 0)

    >>> parse('March')
    datetime.datetime(2015, 3, 16, 0, 0)
    >>> parse('March', settings={'PREFER_DATES_FROM': 'future'})
    datetime.datetime(2016, 3, 16, 0, 0)

    >>> import dateparser
    >>> dateparser.parse("2015")  # default behavior
    datetime.datetime(2015, 3, 27, 0, 0)
    >>> dateparser.parse("2015", settings={"PREFER_MONTH_OF_YEAR": "last"})
    datetime.datetime(2015, 12, 27, 0, 0)
    >>> dateparser.parse("2015", settings={"PREFER_MONTH_OF_YEAR": "current"})
    datetime.datetime(2015, 3, 27, 0, 0)

You can also ignore incomplete dates by setting the `STRICT_PARSING` flag:

    >>> parse('December 2015', settings={'STRICT_PARSING': True})
    None

For more on handling incomplete dates, see the settings documentation.

### Search for Dates in Longer Chunks of Text

Warning

Support for date searching is limited and needs improvement. Contributions are welcome — see contributing.

You can extract dates from longer strings of text. Results are returned as a list of `(substring, datetime)` tuples:

    >>> from dateparser.search import search_dates
    >>> search_dates('Today is 25 of October 2017, so the 27th is in 2 days.')
    [('25 of October 2017', datetime.datetime(2017, 10, 25, 0, 0)), ('the 27th is in 2 days', datetime.datetime(2017, 10, 27, 0, 0))]

### Time Span Detection

The `search_dates` function can also detect time spans such as “past month” or “last week”. When `RETURN_TIME_SPAN` is enabled it returns start and end dates for the detected period:

    >>> search_dates("Messages from the past month", settings={'RETURN_TIME_SPAN': True})
    [('past month (start)', datetime.datetime(2024, 11, 7, 0, 0)),
     ('past month (end)', datetime.datetime(2024, 12, 7, 23, 59, 59, 999999))]

### Settings

You can control multiple behaviors by using the `settings` parameter:

    >>> dateparser.parse('2014-10-12', settings={'DATE_ORDER': 'YMD'})
    datetime.datetime(2014, 10, 12, 0, 0)

    >>> dateparser.parse('2014-10-12', settings={'DATE_ORDER': 'YDM'})
    datetime.datetime(2014, 12, 10, 0, 0)

    >>> dateparser.parse('1 year', settings={'PREFER_DATES_FROM': 'future'})  # Today is 2020-09-23
    datetime.datetime(2021, 9, 23, 0, 0)

    >>> dateparser.parse('tomorrow', settings={'RELATIVE_BASE': datetime.datetime(1992, 1, 1)})
    datetime.datetime(1992, 1, 2, 0, 0)

To see all available settings, check the settings documentation.

### False positives

dateparser will do its best to return a date, dealing with multiple formats and different locales. For that reason it is important that the input is a valid date, otherwise it could return false positives.

To reduce the possibility of receiving false positives, make sure that:

- The input string is a valid date and doesn’t contain any other words or numbers.

- If you know the language or languages beforehand, you add them through the `languages` or `locales` properties.

On the other hand, if you want to exclude any of the default parsers (`timestamp`, `relative-time`…) or change the order in which they are executed, you can do so through the settings PARSERS.

## Installation

Dateparser supports Python 3.10+. You can install it by doing:

    $ pip install dateparser

If you want to use the jalali or hijri calendar, you need to install the `calendars` extra:

    $ pip install dateparser[calendars]

## Supported Calendars

Apart from the Gregorian calendar, dateparser supports the Persian Jalali calendar and the Hijri/Islamic calendar. To use them, install the `calendars` extra (see Installation).

Example using the Persian Jalali calendar:

    >>> from dateparser.calendars.jalali import JalaliCalendar
    >>> JalaliCalendar('جمعه سی ام اسفند ۱۳۸۷').get_date()
    DateData(date_obj=datetime.datetime(2009, 3, 20, 0, 0), period='day', locale=None)

Example using the Hijri/Islamic calendar:

    >>> from dateparser.calendars.hijri import HijriCalendar
    >>> HijriCalendar('17-01-1437 هـ 08:30 مساءً').get_date()
    DateData(date_obj=datetime.datetime(2015, 10, 30, 20, 30), period='day', locale=None)

## Dependencies

dateparser relies on the following libraries:

- dateutil’s module `relativedelta` for its freshness parser.

- convertdate to convert Jalali dates to Gregorian.

- hijridate to convert Hijri dates to Gregorian.

- tzlocal to reliably get local timezone.

- ruamel.yaml (optional) for operations on language files.

## Common use cases

dateparser can be used for a wide variety of purposes, but it stands out when it comes to:

### Consuming data from different sources:

- Scraping: extract dates from different places with several different formats and languages

- IoT: consuming data coming from different sources with different date formats

- Tooling: consuming dates from different logs / sources

- Format transformations: when transforming dates coming from different files (PDF, CSV, etc.) to other formats (database, etc).

### Offering natural interaction with users:

- Tooling and CLI: allow users to write “3 days ago” to retrieve information.

- Search engine: allow people to search by date in an easy / natural format.

- Bots: allow users to interact with a bot easily

## You may also like…

- price-parser - A small library for extracting price and currency from raw text strings.

- number-parser - Library to convert numbers written in the natural language to it’s equivalent numeric forms.

- Scrapy - Web crawling and web scraping framework

## License

BSD3-Clause

## Indices and tables

Contents:

- Installation
- Using DateDataParser
- Settings
  - Date Order
  - Timezone Related Configurations
  - Handling Incomplete Dates
  - Language Detection
  - Default Languages
  - Language Order
  - Optional language detection
  - Other settings
- Custom language detection
  - Built-in implementations
  - Custom implementation
- Supported languages and locales
- Contributing
  - Types of Contributions
  - Get Started!
  - Pull Request Guidelines
  - Guidelines for Editing Translation Data
  - Updating the List of Supported Languages and Locales
- API reference
  - dateparser package
- Credits
- History
  - 1.4.2 (2026-08-04)
  - 1.4.1 (2026-06-15)
  - 1.4.0 (2026-03-26)
  - 1.3.0 (2026-02-04)
  - 1.2.2 (2025-06-26)
  - 1.2.1 (2025-02-05)
  - 1.2.0 (2023-11-17)
  - 1.1.8 (2023-03-22)
  - 1.1.7 (2023-02-02)
  - 1.1.6 (2023-01-12)
  - 1.1.5 (2022-12-29)
  - 1.1.4 (2022-11-21)
  - 1.1.3 (2022-11-03)
  - 1.1.2 (2022-10-20)
  - 1.1.1 (2022-03-17)
  - 1.1.0 (2021-10-04)
  - 1.0.0 (2020-10-29)
  - 0.7.6 (2020-06-12)
  - 0.7.5 (2020-06-10)
  - 0.7.4 (2020-03-06)
  - 0.7.3 (2020-03-06)
  - 0.7.2 (2019-09-17)
  - 0.7.1 (2019-02-12)
  - 0.7.0 (2018-02-08)
  - 0.6.0 (2017-03-13)
  - 0.5.1 (2016-12-18)
  - 0.5.0 (2016-09-26)
  - 0.4.0 (2016-06-17)
  - 0.3.5 (2016-04-27)
  - 0.3.4 (2016-03-03)
  - 0.3.3 (2016-02-29)
  - 0.3.2 (2016-01-25)
  - 0.3.1 (2015-10-28)
  - 0.3.0 (2015-07-29)
  - 0.2.1 (2015-07-13)
  - 0.2.0 (2015-06-17)
  - 0.1.0 (2014-11-24)

- Index

- Module Index

- Search Page