python-dateutil

2.9.0.post0 verified Tue May 12 auth: no python install: verified quickstart: verified maintenance

python-dateutil provides powerful extensions to Python's standard datetime module, including flexible date/time string parsing, relative delta arithmetic, recurrence rules (RFC 2445 superset), and rich timezone support via tzfile, TZ strings, and Windows registry. Current version is 2.9.0.post0 (released 2024-03-01). The project is considered functionally stable but upstream activity is slow; Fedora has flagged it as unmaintained. The PyPI install name (python-dateutil) differs from the importable name (dateutil).

pip install python-dateutil

Common errors

error ModuleNotFoundError: No module named 'dateutil' ↓

cause The 'python-dateutil' package, which provides the 'dateutil' module, is not installed in the Python environment.

fix

pip install python-dateutil

error ValueError: Unknown string format ↓

cause The 'dateutil.parser.parse' function could not interpret the provided date string because its format was ambiguous or not recognized.

fix

Provide date strings in clear, standard formats, use 'parser.isoparse' for ISO 8601, or pass 'dayfirst=True' / 'yearfirst=True' to 'parser.parse' for ambiguous formats.

error AttributeError: module 'dateutil' has no attribute 'parse' ↓

cause The 'parse' function is located within the 'dateutil.parser' submodule, but the user attempted to call it directly from the top-level 'dateutil' module.

fix

Import the 'parser' submodule explicitly, e.g., 'from dateutil import parser' or 'import dateutil.parser'.

error TypeError: unsupported operand type(s) for +: 'datetime.date' and 'relativedelta' ↓

cause The 'relativedelta' object is being added to a 'datetime.date' object, which does not support direct arithmetic with 'relativedelta'; it only works with 'datetime.datetime' objects.

fix

Convert the 'datetime.date' object to a 'datetime.datetime' object before adding the 'relativedelta', or ensure you are working with 'datetime.datetime' objects from the start.

Warnings

gotcha parser.parse() silently guesses ambiguous dates like '04/05/2024' using dayfirst=False (MM/DD) by default. Non-US date strings will be parsed incorrectly unless dayfirst=True is set explicitly. ↓

fix Always pass dayfirst=True for DD/MM/YYYY input, or use isoparse() for unambiguous ISO 8601 strings.

gotcha parser.parse() returns a timezone-naive datetime when no timezone is present in the input string, which can silently cause incorrect comparisons with aware datetimes. ↓

fix Check dt.tzinfo after parsing, or pass a default timezone via the tzinfos parameter, or use dateutil.tz.tzutc() to attach UTC explicitly.

breaking Since 2.8.1 parse() raises dateutil.parser.ParserError (a ValueError subclass) instead of plain ValueError. Code catching ValueError still works, but catching only the base Exception may need updating. ↓

fix Catch ParserError for precision: from dateutil.parser import ParserError; except ParserError: ...

gotcha fuzzy=True parsing can silently extract numbers from arbitrary strings as date components (e.g. parse('lbl2vec at 7pm', fuzzy=True) extracts '2' as a day). This makes fuzzy parsing unsafe for untrusted or unexpected input. ↓

fix Use fuzzy=False (default) or fuzzy_with_tokens=True and inspect the ignored tokens tuple to validate what was consumed.

gotcha rrule dtstart is NOT included as the first occurrence unless it independently satisfies the recurrence rule — this diverges from RFC 2445 behavior. ↓

fix To include dtstart unconditionally, use rruleset and add dtstart with ruleset.rdate(dtstart).

gotcha gettz() returns None silently when a timezone name cannot be resolved (e.g. on Windows without the tzdata package installed). Passing None as tzinfo produces a naive datetime without error. ↓

fix Always assert the result: tz = gettz('America/New_York'); assert tz is not None. Install tzdata package on Windows/Docker environments.

deprecated The project still ships the six compatibility shim as a hard dependency. Fedora has flagged the project as effectively unmaintained upstream with possible unaddressed security issues. New greenfield projects should consider zoneinfo (Python 3.9+ stdlib) + dateutil only for relativedelta/rrule features. ↓

fix For pure timezone handling on Python 3.9+, prefer zoneinfo.ZoneInfo from the stdlib. For relativedelta on Python 3, evaluate whether stdlib timedelta suffices for your use case.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.6M

3.10 slim (glibc) - - 0.02s 19M

3.11 alpine (musl) - - 0.05s 20.6M

3.11 slim (glibc) - - 0.04s 21M

3.12 alpine (musl) - - 0.04s 12.4M

3.12 slim (glibc) - - 0.04s 13M

3.13 alpine (musl) - - 0.04s 12.1M

3.13 slim (glibc) - - 0.04s 13M

3.9 alpine (musl) - - 0.04s 18.1M

3.9 slim (glibc) - - 0.03s 19M

Imports

parser.parse

wrong

import dateutil; dateutil.parser.parse('2024-01-15')  # works on 3.7+ via lazy import but not guaranteed in all environments

correct

from dateutil import parser; parser.parse('2024-01-15')

Always import the submodule explicitly for clarity. The top-level lazy-import shortcut (PEP 562, added in 2.9.0) only works on Python 3.7+.

parser.isoparse
```
from dateutil.parser import isoparse
```
Use isoparse() for strict ISO 8601 strings instead of parse(); parse() is more permissive and may silently misinterpret ambiguous ISO strings.
relativedelta
wrong
```
from dateutil.relativedelta import *
```
correct
```
from dateutil.relativedelta import relativedelta
```
Wildcard import pulls in weekday constants (MO, TU, ...) that can shadow calendar/rrule symbols; prefer explicit import.
rrule / DAILY / WEEKLY / MONTHLY / YEARLY
```
from dateutil.rrule import rrule, DAILY, WEEKLY, MONTHLY, YEARLY, rruleset
```
Frequency constants (DAILY, WEEKLY, etc.) must be imported from dateutil.rrule; they are not available at the top-level dateutil namespace.
gettz
```
from dateutil.tz import gettz, tzutc, tzlocal
```
gettz() returns None (not an exception) when the timezone name is unrecognized — always check for None before using the result.
ParserError
wrong
```
except ValueError
```
correct
```
from dateutil.parser import ParserError
```
Since 2.8.1 parse() raises ParserError (a ValueError subclass) on failure. Catching only ValueError still works but catching ParserError is more precise.

Quickstart verified last tested: 2026-04-23

Demonstrates flexible string parsing, isoparse, relativedelta month arithmetic, timezone handling with gettz, and explicit dayfirst flag for ambiguous dates.

from datetime import datetime
from dateutil import parser
from dateutil.relativedelta import relativedelta
from dateutil.tz import gettz, tzutc

# 1. Flexible string parsing
dt = parser.parse("March 15, 2024 3:30 PM")
print("Parsed:", dt)

# 2. ISO 8601 with timezone
dt_aware = parser.isoparse("2024-03-15T15:30:00+05:30")
print("ISO aware:", dt_aware)

# 3. Relative delta arithmetic (month-aware)
now = datetime(2024, 1, 31, tzinfo=tzutc())
one_month_later = now + relativedelta(months=1)
print("One month later:", one_month_later)  # 2024-02-29 (leap year)

# 4. Timezone-aware datetime
nyc = gettz("America/New_York")
if nyc is None:
    raise RuntimeError("Could not resolve timezone; install tzdata package")
dt_nyc = datetime(2024, 3, 15, 12, 0, tzinfo=nyc)
print("NYC time:", dt_nyc)

# 5. Ambiguous date: always set dayfirst/yearfirst explicitly
ambiguous = parser.parse("04/05/2024", dayfirst=False)  # May 4
print("MM/DD:", ambiguous.date())