
python parser for human readable dates
Repo scrapinghub/dateparser, read from GitHub 1 min ago. scrapinghub has not joined Take My Repo.
scrapinghub/dateparser is a public repo on GitHub by scrapinghub. python parser for human readable dates. It declares the BSD-3-Clause license on GitHub. It is written mainly in Python, has 2,867 stars and last changed on 2026-11-18. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
Key Features • How To Use • Installation • Common use cases • You may also like... • License
"two weeks ago" or "tomorrow"), timestamps,
etc."August 14, 2015 EST", "21 July 2013 10:15 pm +0500"...)Do you want to try it out without installing any dependency? Now you can test it quickly by visiting this online demo!
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)
The formats are tried first. A date string that none of them parses is then
parsed as if no formats were given, so a number that is out of range for a
format can be read as another part of the date (32 is not a day, but it is
a valid two-digit year). To accept only the given formats, set PARSERS to
['custom-formats'], which also turns off timestamps, relative dates and
free-form dates:
>>> dateparser.parse('32 DEC 10', date_formats=['%d %b %y']) datetime.datetime(2032, 12, 10, 0, 0) >>> dateparser.parse('32 DEC 10', date_formats=['%d %b %y'], settings={'PARSERS': ['custom-formats']}) None
>>> 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) >>> parse('next Wednesday') datetime.datetime(2015, 6, 3, 0, 0)
In English, last, this and next before a weekday mean its closest
occurrence before, on or after, and after the current date, respectively,
regardless of the PREFER_DATES_FROM setting. So this Wednesday and
next Wednesday are the same date except on a Wednesday. They do not apply
to wed, sat and sun, which are also common English words.
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.
>>> # 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.
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.
>>> 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.
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))]
Pass languages when you know them: language detection is slow and
error-prone on short text. If no date is found, None is returned:
>>> search_dates('Lancé le 4 octobre 1957.', languages=['fr']) [('le 4 octobre 1957', datetime.datetime(1957, 10, 4, 0, 0))] >>> search_dates('Rien à voir.', languages=['fr']) None
See the API reference
for other parameters, such as strategy.
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.
For example, assuming the current date and time is December 7, 2024, 15:30:
>>> search_dates("Messages from the past month", settings={'RETURN_TIME_SPAN': True}) [('past month (start)', datetime.datetime(2024, 11, 7, 15, 30)), ('past month (end)', datetime.datetime(2024, 12, 7, 15, 30))]
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.
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:
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.
Dateparser supports Python 3.10+. You can install it by doing:
$ pip install dateparser
If you want to use a non-Gregorian calendar, you need to install the
calendars extra:
$ pip install dateparser[calendars]
Apart from the Gregorian calendar, dateparser supports the Persian Jalali
calendar, the Hijri/Islamic calendar, the French Republican calendar and
the Minguo calendar. To use the first three, 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, parts=('year', 'month', 'day'))
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, parts=('year', 'month', 'day', 'time'))
Example using the French Republican calendar:
>>> from dateparser.calendars.french_republican import FrenchRepublicanCalendar >>> FrenchRepublicanCalendar('18 brumaire an VIII').get_date() DateData(date_obj=datetime.datetime(1799, 11, 9, 0, 0), period='day', locale=None)
Example using the Minguo calendar:
>>> from dateparser.calendars.minguo import MinguoCalendar >>> MinguoCalendar('民國101年5月25日 08:36').get_date() DateData(date_obj=datetime.datetime(2012, 5, 25, 8, 36), period='day', locale=None)
dateparser relies on the following libraries:
relativedelta for its freshness parser.dateparser can be used for a wide variety of purposes, but it stands out when it comes to:
scrapinghub/dateparser is a public repo on GitHub by scrapinghub. python parser for human readable dates.
It declares the BSD-3-Clause license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-18. GitHub counts 215 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Lightweight, scriptable browser as a service with an HTTP API

This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/scrapinghub/dateparserTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.