Registry / data / python-dateutil

python-dateutil

library2.9.0.post0pypypi✓ verified 27d ago

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).

data serialization

pip install python-dateutil

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PYTHON-DATEUTIL

python-dateutil

datapythonv2.9.0.post0

Install

1.8s avg

Import

37ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.9.0.post0 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.038s · 18.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.036s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

parser.parse

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

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

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

✓ from dateutil.relativedelta import relativedelta

✗ from dateutil.relativedelta import *

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

✓ from dateutil.parser import ParserError

✗ except ValueError

Since 2.8.1 parse() raises ParserError (a ValueError subclass) on failure. Catching only ValueError still works but catching ParserError is more precise.

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())

Debug

Known issues

gotchaparser.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.

affects: all

gotchaparser.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.

affects: all

breakingSince 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: ...

affects: >=2.8.1

gotchafuzzy=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.

affects: all

gotcharrule 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).

affects: all

gotchagettz() 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.

affects: all

deprecatedThe 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.

affects: <=2.9.0.post0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'dateutil'

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

fix

pip install python-dateutil

ValueError: Unknown string format

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.

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

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'.

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

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.

Upgrade

Version history

2.9.0.post0latest on PyPI · released Mar 1, 2024

Audit

Dependencies

sixrequiredPython 2/3 compatibility shim; still a hard runtime dependency in 2.9.x even on Python 3

tzdataoptionalIANA timezone database on platforms without /usr/share/zoneinfo (e.g. Windows); needed for dateutil.tz.gettz() to resolve IANA names reliably

Agent activity

43 hits · last 30 days

node

Resources

githubhttps://github.com/dateutil/dateutil ↗

packagehttps://pypi.org/project/python-dateutil/ ↗

docshttps://dateutil.readthedocs.io/en/stable/ ↗