python-dateutil is one of those packages almost every Python project has somewhere in its dependency tree. Version 4.0.0, published on 1 November 2026, is a new major release. Most of it is clean-up, but one change can break real code: isoparse is now strict about the digits in each date and time field. Strings it used to accept now raise ValueError.

This guide explains what changed, shows how to find code that will break, and gives you a safe upgrade path. All details come from the official dateutil 4.0.0 release notes.

What changed in dateutil 4.0

Change Impact
Requires Python 3.11+ Older interpreters stay on 2.x
No longer depends on six One fewer dependency; private Python 2 helpers removed
Stricter isoparse and isoparser Malformed ISO strings now raise ValueError
tzical applies the same check to offsets Bad TZOFFSETFROM / TZOFFSETTO values are rejected
Cached rrule iteration hang fixed No more infinite loops with shared caches
Pickling fixes for tzutc / tzoffset Unpickled objects are the expected singletons
relativedelta(yearday=366) fixed Now gives 31 December in leap years
Build backend is now Hatchling Only matters if you build from source

Step 1: Check your Python version

python --version

If you are on Python 3.10 or older, pip will keep installing 2.x. That is fine for now, but plan the Python upgrade, because new fixes will land on 4.x.

Step 2: Understand the stricter isoparse

In 4.0, parser.isoparse and the isoparser methods parse_isodate, parse_isotime and parse_tzstr require each numeric field to be exactly the expected number of ASCII digits. The release notes give these examples of strings that used to parse and now fail:

  • 20200728121240 – a run of digits that was previously read as a time of 21:24
  • 2014- 4-21 – a space instead of a leading zero
  • 2_14-04-21 – an underscore inside the year
  • offsets such as +-1:00

Here is the behaviour you should now expect:

from dateutil.parser import isoparse

print(isoparse("2026-11-18T09:30:00+05:30"))  # fine
print(isoparse("2026-11-18"))                  # fine

for bad in ["2014- 4-21", "2_14-04-21", "2026-11-18T09:30:00+-1:00"]:
    try:
        isoparse(bad)
    except ValueError as exc:
        print("rejected:", bad, "->", exc)

This is a good change. Those inputs were never valid ISO 8601, and silently accepting them could turn a typo into a wrong timestamp. But if your app ingests messy data from CSV files, user forms or third-party APIs, some rows that used to “work” will now raise.

Step 3: Find risky call sites

Search your code for the functions that changed:

grep -rnE "isoparse|isoparser|parse_isodate|parse_isotime|parse_tzstr|tzical" --include=*.py .

For each hit, ask: where does the string come from? Hard-coded test values and timestamps produced by datetime.isoformat() are safe. Data typed by humans or exported by other systems is where surprises hide.

Step 4: Test old data before you upgrade

The safest way to know if 4.0 breaks you is to run real samples through both versions. Save a sample of the date strings your app parses, one per line, in dates.txt, then run this script:

# check_dates.py
import sys
from dateutil import __version__
from dateutil.parser import isoparse

failures = 0
with open("dates.txt", encoding="utf-8") as fh:
    for line_no, raw in enumerate(fh, start=1):
        value = raw.strip()
        if not value:
            continue
        try:
            isoparse(value)
        except ValueError as exc:
            failures += 1
            print(f"line {line_no}: {value!r} -> {exc}")

print(f"dateutil {__version__}: {failures} failures")
sys.exit(1 if failures else 0)

Run it in two throwaway virtual environments:

python -m venv /tmp/du2 && /tmp/du2/bin/pip install "python-dateutil<4" -q
python -m venv /tmp/du4 && /tmp/du4/bin/pip install "python-dateutil>=4" -q

/tmp/du2/bin/python check_dates.py
/tmp/du4/bin/python check_dates.py

Any line that passes on 2.x but fails on 4.0 is data you need to handle.

Step 5: Handle bad input on purpose

Do not just catch and ignore the new errors. Decide what each source should do. A common pattern is to normalise known quirks first and reject everything else clearly:

import re
from datetime import datetime
from dateutil.parser import isoparse

_SPACE_PADDED = re.compile(r"^(\d{4})-\s?(\d{1,2})-\s?(\d{1,2})$")

def parse_date(value: str) -> datetime:
    value = value.strip()
    try:
        return isoparse(value)
    except ValueError:
        pass

    # Known quirk from an old export: "2014- 4-21"
    match = _SPACE_PADDED.match(value)
    if match:
        year, month, day = (int(part) for part in match.groups())
        return datetime(year, month, day)

    raise ValueError(f"Unsupported date format: {value!r}")

If you really need loose parsing of free-form text, dateutil.parser.parse is the function designed for that. isoparse is meant for strict ISO 8601.

Other fixes worth knowing

Cached rrule no longer hangs

Before 4.0, iterating a cached rrule or rruleset could hang forever if another iterator had already filled the cache, for example when the same cached rule was added to an rruleset twice. That is fixed, so recurring-event code becomes safer without changes.

Leap-year yearday

relativedelta(yearday=366) now resolves to 31 December in leap years. Earlier it returned 30 December, the same as yearday=365.

from datetime import date
from dateutil.relativedelta import relativedelta

print(date(2028, 1, 1) + relativedelta(yearday=366))  # 2028-12-31

If you have a test that asserted the old 30 December result, update it.

Pickling time zones

Unpickling tzutc now returns the dateutil.tz.UTC singleton, and unpickling a tzoffset returns the same object as calling tzoffset(name, offset). Identity checks such as dt.tzinfo is tz.UTC behave more predictably after data passes through caches or multiprocessing.

Removed Python 2 helpers

The six dependency is gone, along with Python 2 helpers that were never public, such as dateutil.tz.tzname_in_python2. If any code imported those private names, it will now fail with an ImportError.

Pin carefully during rollout

If you cannot test everything at once, pin the old major version in production and upgrade service by service:

# requirements.txt
python-dateutil>=2.9,<4

Then move each service to python-dateutil>=4,<5 once its date data passes the check above.

Takeaway

dateutil 4.0 is mostly a modernisation: Python 3.11+, no six, and several long-standing bugs fixed. The one change to plan for is the stricter isoparse. Run your real date strings through 4.0 before upgrading, handle any failures on purpose, and you get safer parsing with no surprises.