dateparser

library1.4.0pypypi✓ verified 52d ago

Dateparser is a Python library (v1.4.0) designed to parse dates from various formats, including natural language and localized strings, often found on web pages. It aims to simplify datetime string conversion, timezone handling, and ambiguous date resolution. The library has an active development cycle with minor versions released every few months, frequently adding new language support and parsing features.

data serialization

pip install dateparser

github ↗package ↗changelog ↗

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.950 runs

installs and imports cleanly · install 0.0s · import 0.960s · 33.5MB

glibc

py 3.10–3.950 runs

installs and imports cleanly · install 3.7s · import 0.870s · 34MB

32MB installed

● package 32MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ from dateparser import parse

DateDataParser

✓ from dateparser.date import DateDataParser

For advanced use cases like caching detected languages and custom parsing behavior.

The most common way to parse dates is using the `dateparser.parse()` function. It automatically detects formats and languages, and can be configured with settings for more control, such as handling relative dates or specific timezones.

import dateparser from datetime import datetime # Basic parsing date_obj1 = dateparser.parse('12/12/12') print(f"'12/12/12' parsed as: {date_obj1}") # Parsing a relative date date_obj2 = dateparser.parse('2 days ago') print(f"'2 days ago' parsed as: {date_obj2}") # Parsing a date with specific language settings date_obj3 = dateparser.parse('Martes 21 de Octubre de 2014', languages=['es']) print(f"'Martes 21 de Octubre de 2014' (Spanish) parsed as: {date_obj3}") # Parsing with timezone preference date_obj4 = dateparser.parse('August 14, 2015 EST', settings={'TIMEZONE': 'America/New_York', 'RETURN_AS_TIMEZONE_AWARE': True}) print(f"'August 14, 2015 EST' with timezone preference: {date_obj4}")

Debug

Known issues

breakingPython 3.9 support was dropped in `dateparser` v1.3.0. Ensure your environment uses Python 3.10 or newer.

fix

Upgrade to Python >=3.10.

affects: >=1.3.0

breakingIn v1.4.0, security fixes removed import-time loading of timezone offset data from pickle and replaced `eval()` use with strict boolean parsing for `no_word_spacing`. Users relying on custom deserialized data or specific locale metadata processing might experience changes.

fix

Review any custom logic that interacted with locale metadata or expected specific deserialization behavior. Adapt to stricter parsing rules.

affects: >=1.4.0

breakingIn v1.0.0, `DateDataParser.get_date_data()` changed its return type from a `dict` to a `DateData` object. Additionally, providing wrong settings now raises `SettingValidationError` instead of being silently ignored.

fix

Update code expecting a dictionary from `get_date_data()` to handle a `DateData` object. Validate settings passed to avoid `SettingValidationError`.

affects: >=1.0.0

gotchaDateparser returns naive `datetime` objects by default if the input string lacks timezone information. To ensure timezone-aware `datetime` objects, specify `TIMEZONE` and `RETURN_AS_TIMEZONE_AWARE=True` in settings.

fix

Pass `settings={'TIMEZONE': 'UTC', 'RETURN_AS_TIMEZONE_AWARE': True}` (or your desired timezone) to `dateparser.parse()` for consistent timezone-aware results.

affects: all

gotchaAmbiguous date formats (e.g., '03/11/2024') can lead to incorrect parsing (e.g., MM/DD/YYYY vs. DD/MM/YYYY). To resolve this, explicitly set the `DATE_ORDER` setting or provide known `languages` or `locales`.

fix

Use `settings={'DATE_ORDER': 'DMY'}` (or 'MDY', 'YMD' as appropriate) or `languages=['en-US']` to guide the parser.

affects: all

gotchaWhen parsing incomplete dates (e.g., 'March 15', '2024'), the library fills in missing components based on current date context. For consistent behavior, use `PREFER_DATES_FROM`, `PREFER_DAY_OF_MONTH`, or `PREFER_MONTH_OF_YEAR` settings.

fix

Configure settings like `settings={'PREFER_DATES_FROM': 'past'}` or `{'PREFER_MONTH_OF_YEAR': 'last'}` to control how missing date parts are inferred.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'dateparser'

The dateparser library has not been installed in the Python environment where the code is being executed.

fix

Install the package using pip: `pip install dateparser`

AttributeError: module 'dateparser' has no attribute 'parse'

The 'parse' function is incorrectly accessed directly from the 'dateparser' module instead of being imported from it.

fix

Import the 'parse' function directly: `from dateparser import parse`

TypeError: 'NoneType' object is not callable

The `dateparser.parse()` function returns `None` when it cannot successfully parse the input string into a date, and subsequent code attempts to call a method on this `None` object. This often happens with ambiguous, malformed, or incomplete date strings, or strings containing extraneous text.

fix

Always check if the result of `dateparser.parse()` is `None` before attempting further operations. For strings with extra text, consider using `dateparser.search.search_dates()` instead.

ValueError: Unknown Language

This error occurs when an invalid or unsupported language code is provided to dateparser's functions or settings, or if the 'languages' argument is not supplied as a list.

fix

Ensure that the language codes are valid ISO 639-1 codes (e.g., `['en']`) and that the `languages` argument is always provided as a list.

Upgrade

Version history

1.4.0latest on PyPI

Audit

Dependencies

python-dateutilrequiredUsed for 'relativedelta' in freshness parsing.

convertdaterequiredRequired for converting Jalali dates to Gregorian.

hijridaterequiredRequired for converting Hijri dates to Gregorian (migrated from `hijri-converter` in v1.2.1).

tzlocalrequiredUsed to reliably get the local timezone.

ruamel.yamloptionalOptional dependency for operations on language files.

Agent activity

14 hits · last 30 days

node

seranking-bot

ahrefsbot

amazonbot

Resources

githubhttps://github.com/scrapinghub/dateparser ↗

packagehttps://pypi.org/project/dateparser/ ↗

changeloghttps://dateparser.readthedocs.io/en/latest/history.html ↗