parsedatetime

2.6 verified Tue May 12 auth: no python install: verified

parsedatetime is a Python module that can parse human-readable date/time strings like "tomorrow at 3pm" or "next Tuesday". It is currently at version 2.6 and primarily targets Python 3, with v2.6 maintaining Python 2.7 compatibility. Releases occur periodically, with significant updates and bug fixes.

pip install parsedatetime

Common errors

error AttributeError: module 'parsedatetime' has no attribute 'parseDT' ↓

cause The `parseDT` method is an instance method of the `Calendar` class and must be called on an instantiated `Calendar` object, not directly on the `parsedatetime` module.

fix

First, create an instance of parsedatetime.Calendar() and then call its parseDT method:

import parsedatetime as pdt
import datetime

cal = pdt.Calendar()
result, parse_status = cal.parseDT('tomorrow', datetime.datetime.now())
print(result)

error AttributeError: 'tuple' object has no attribute 'year' ↓

cause The `parseDT` method returns a tuple `(datetime_object, parse_status)`, but the user attempted to access datetime attributes (like 'year', 'month', 'day') directly on this tuple instead of on the datetime object within it.

fix

Unpack the tuple into separate variables for the datetime object and the parse status, or access the datetime object using its index [0]:

import parsedatetime as pdt
import datetime

cal = pdt.Calendar()

# Option 1: Unpack the tuple
dt_obj, parse_status = cal.parseDT('next Tuesday', datetime.datetime.now())
print(dt_obj.year, dt_obj.month, dt_obj.day)

# Option 2: Access by index
dt_obj = cal.parseDT('next Tuesday', datetime.datetime.now())[0]
print(dt_obj.year, dt_obj.month, dt_obj.day)

error ModuleNotFoundError: No module named 'parsedatetime' ↓

cause The `parsedatetime` package is not installed in the Python environment being used, or the environment's `PYTHONPATH` does not include the installation location.

fix

Install the package using pip in your terminal:

pip install parsedatetime

error TypeError: unsupported operand type(s) for -: 'NoneType' and 'datetime.timedelta' ↓

cause This error typically occurs when `None` is passed as the `sourceTime` (reference date/time) argument to `parseDT`, but the method expects a valid `datetime.datetime` object to calculate relative dates.

fix

Ensure that a valid datetime.datetime object (e.g., datetime.datetime.now()) is always provided for the sourceTime argument when calling parseDT:

import parsedatetime as pdt
import datetime

cal = pdt.Calendar()

# Correct: Pass a datetime object as sourceTime
dt_obj, parse_status = cal.parseDT('tomorrow', datetime.datetime.now())
print(dt_obj)

# Incorrect (would cause the error):
# dt_obj, parse_status = cal.parseDT('tomorrow', None)

Warnings

breaking The `parse()` method's return value changed significantly around version 2.0. It now consistently returns a tuple `(time_struct, parse_status)`. Code relying on direct `datetime` or `time_struct` return without checking `parse_status` or handling the tuple will break. ↓

fix Always expect a `(time_struct, parse_status)` tuple from `cal.parse()`. Check `parse_status` (0 for failure, 1 for date, 2 for time, 3 for datetime) before converting `time_struct` to a `datetime` object, e.g., `datetime(*time_struct[:6])`.

deprecated The 'flag style' for instantiating `Calendar()` (e.g., `Calendar(parsedatetime.constants.getConstants())`) was deprecated in version 2.0 in favor of a 'context style'. ↓

fix Instantiate `Calendar()` directly without arguments for default behavior, or use `Calendar(version=parsedatetime.VERSION_CONTEXT_STYLE)` for explicit context-aware parsing if needed, though this is often the default behavior in newer versions.

gotcha When parsing incomplete human-readable dates (e.g., "Jan 1st"), `parsedatetime` implicitly guesses the year based on the current date (`sourceTime`). This can lead to unexpected results if the inferred year doesn't match expectations, especially for dates far in the past or future. ↓

fix For critical date parsing, always provide a `sourceTime` argument to `cal.parse()` to set a clear reference point, or explicitly include the year in the input string. Example: `cal.parse("Jan 1st", sourceTime=datetime(2025, 6, 1))`.

gotcha While v2.6 includes Python 2.7 compatibility, the library's development now primarily targets Python 3. Users on older Python 2.x environments may encounter unexpected issues or lack of support in future releases. ↓

fix Prefer using `parsedatetime` in a Python 3 environment. If Python 2.7 is necessary, ensure you are on `parsedatetime` version 2.6 and thoroughly test your parsing logic. Upgrade to Python 3 where possible.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.05s 18.1M

3.10 alpine (musl) - - 0.05s 18.1M

3.10 slim (glibc) wheel 1.5s 0.03s 19M

3.10 slim (glibc) - - 0.04s 19M

3.11 alpine (musl) wheel - 0.09s 20.0M

3.11 alpine (musl) - - 0.10s 20.0M

3.11 slim (glibc) wheel 1.6s 0.07s 20M

3.11 slim (glibc) - - 0.07s 20M

3.12 alpine (musl) wheel - 0.07s 11.9M

3.12 alpine (musl) - - 0.07s 11.9M

3.12 slim (glibc) wheel 1.5s 0.07s 12M

3.12 slim (glibc) - - 0.07s 12M

3.13 alpine (musl) wheel - 0.06s 11.6M

3.13 alpine (musl) - - 0.06s 11.5M

3.13 slim (glibc) wheel 1.4s 0.05s 12M

3.13 slim (glibc) - - 0.06s 12M

3.9 alpine (musl) wheel - 0.05s 17.6M

3.9 alpine (musl) - - 0.05s 17.6M

3.9 slim (glibc) wheel 1.7s 0.04s 18M

3.9 slim (glibc) - - 0.04s 18M

Imports

Calendar
wrong
```
import parsedatetime.parsedatetime as pdt
cal = pdt.Calendar()
```
correct
```
import parsedatetime
cal = parsedatetime.Calendar()
```
The direct import from `parsedatetime` is the current standard. Older examples or codebases might use `parsedatetime.parsedatetime`.

Quickstart last tested: 2026-04-24

Initializes the Calendar object and demonstrates parsing a human-readable date/time string, converting the `time.struct_time` output to a standard `datetime` object, and using a `sourceTime` for relative parsing. The `parse()` method returns a tuple: `(time_struct, parse_status)`, where `parse_status` indicates success and the type of information parsed (e.g., date, time, or datetime).

from datetime import datetime
import parsedatetime

cal = parsedatetime.Calendar()

# Parse a human-readable string
time_struct, parse_status = cal.parse("tomorrow at 3pm")

# Convert the result to a Python datetime object
if parse_status != 0:
    dt_object = datetime(*time_struct[:6])
    print(f"Parsed 'tomorrow at 3pm' as: {dt_object}")

# Example with a specific starting point (sourceTime)
from datetime import datetime, timedelta
source_time = datetime(2026, 1, 1, 10, 0, 0) # Jan 1, 2026, 10:00 AM
time_struct_next, _ = cal.parse("next friday", source_time)
dt_object_next = datetime(*time_struct_next[:6])
print(f"Parsed 'next friday' from {source_time} as: {dt_object_next}")