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:242014- 4-21– a space instead of a leading zero2_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.
