Typing stubs for python-dateutil
raw JSON → 2.9.0.20260323 verified Tue May 12 auth: no python install: stale quickstart: stale
types-python-dateutil provides static typing stubs for the popular `python-dateutil` library. It allows type checkers like Mypy or Pyright to verify code that uses `python-dateutil`, catching potential type-related errors before runtime. This package is part of the typeshed project and aims to provide accurate annotations for `python-dateutil==2.9.*`. Updates are released frequently, often daily, directly from the typeshed repository. The current version is 2.9.0.20260323.
pip install types-python-dateutil Common errors
error error: Library 'python-dateutil' has no type annotations ↓
cause Mypy cannot find type annotations for the `python-dateutil` library because the `types-python-dateutil` stub package is not installed or not discoverable by Mypy.
fix
Install the type stub package:
pip install types-python-dateutil error Cannot find implementation or library stub for module 'dateutil' ↓
cause Pyright is unable to locate the type stub files for the `dateutil` module, indicating that `types-python-dateutil` is either not installed or not in Pyright's configured stub paths.
fix
Install the type stub package:
pip install types-python-dateutil error error: "parser" has no attribute "isoparse" [attr-defined] ↓
cause The installed `types-python-dateutil` stub package is outdated or does not fully reflect the API of the `python-dateutil` runtime library you are using, leading to a type checker error for a valid attribute.
fix
Upgrade both the
python-dateutil library and its type stubs to their latest versions to ensure compatibility: pip install --upgrade python-dateutil types-python-dateutil Warnings
gotcha The `types-python-dateutil` package provides stubs for a specific major/minor version range of `python-dateutil` (e.g., `2.9.*`). Using a significantly different version of the runtime `python-dateutil` library may lead to inaccurate type checking results or errors, as API changes in `python-dateutil` might not be reflected in the stubs for a different version range. ↓
fix Always install `types-python-dateutil` that matches the major/minor version of your `python-dateutil` dependency. Pinning versions in your `requirements.txt` (e.g., `python-dateutil==2.9.0` and `types-python-dateutil==2.9.0.YYYYMMDD`) is recommended.
gotcha Type checkers (like Mypy) might sometimes fail to pick up installed stub packages, especially in complex environments or when using tools like `pre-commit` hooks. This can result in 'Missing stubs' errors even when `types-python-dateutil` is installed. ↓
fix Ensure your type checker is correctly configured to find third-party stubs. For Mypy in `pre-commit`, you might need to explicitly add `types-python-dateutil` to `additional_dependencies` in your `.pre-commit-config.yaml`. For local runs, ensure `types-python-dateutil` is in your environment's dependencies (e.g., `dev-requirements.txt`).
gotcha While typeshed aims to release stub packages frequently (up to once a day), there can be a slight delay between a new `python-dateutil` release and the corresponding update to `types-python-dateutil`. During this period, very new features or breaking changes in the latest `python-dateutil` might not yet have accurate type annotations. ↓
fix Be aware of this potential lag. If you encounter type checking errors or missing annotations for very new `python-dateutil` features, you may need to wait for the next `types-python-dateutil` release or temporarily ignore specific type checking issues. Contributing to typeshed is also an option if you identify missing annotations.
breaking Due to the nature of type stubs, any version bump of `types-python-dateutil` can introduce changes that might cause your code to fail type checking, even if the runtime behavior of `python-dateutil` has not changed. This often happens when stricter or more accurate types are introduced. ↓
fix It is advisable to pin the version of `types-python-dateutil` in your project's dependencies to ensure consistent type checking results across builds and environments. Regularly review and update the pinned version to benefit from improved stub accuracy.
gotcha `types-python-dateutil` requires Python >=3.10. Using it with older Python versions might lead to installation issues or type checking inconsistencies if the underlying `python-dateutil` library behaves differently or relies on features not available in older Python versions. ↓
fix Ensure your project uses Python 3.10 or newer. If you must support older Python versions, you might need to use an older `types-python-dateutil` version (if available) that is compatible with both your Python version and your `python-dateutil` version, or consider disabling type checking for `dateutil` imports in those environments.
breaking The `python-dateutil` library is not installed or not found in the Python environment, leading to a `ModuleNotFoundError` when attempting to import `dateutil`. ↓
fix Ensure `python-dateutil` is installed in your environment. You can typically install it using pip: `pip install python-dateutil`. If using a `requirements.txt` file, ensure `python-dateutil` is listed there.
breaking The `ModuleNotFoundError: No module named 'dateutil'` indicates that the `python-dateutil` runtime library is not installed in the execution environment. This package is a mandatory runtime dependency for code that imports from `dateutil`. ↓
fix Ensure the `python-dateutil` package is installed in your environment (e.g., via `pip install python-dateutil`). Verify that it is listed in your project's dependency management file (e.g., `requirements.txt`) and that your build/deployment process correctly installs all runtime dependencies.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - - 17.9M
3.10 alpine (musl) - - - -
3.10 slim (glibc) wheel 1.5s - 18M
3.10 slim (glibc) - - - -
3.11 alpine (musl) wheel - - 19.7M
3.11 alpine (musl) - - - -
3.11 slim (glibc) wheel 1.5s - 20M
3.11 slim (glibc) - - - -
3.12 alpine (musl) wheel - - 11.6M
3.12 alpine (musl) - - - -
3.12 slim (glibc) wheel 1.4s - 12M
3.12 slim (glibc) - - - -
3.13 alpine (musl) wheel - - 11.3M
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 1.4s - 12M
3.13 slim (glibc) - - - -
3.9 alpine (musl) wheel - - 17.4M
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 1.7s - 18M
3.9 slim (glibc) - - - -
Imports
- parse
from dateutil.parser import parse - relativedelta
from dateutil.relativedelta import relativedelta - tz
from dateutil import tz - UTC wrong
from dateutil.tz import tzutc()correctfrom dateutil.tz import UTC
Quickstart stale last tested: 2026-04-23
from datetime import datetime
from dateutil.parser import parse
from dateutil.relativedelta import relativedelta, MO
# Enable type checking in your editor or via a tool like Mypy
# E.g., run `mypy your_script.py`
def process_date_string(date_str: str) -> datetime:
"""Parses a date string and returns a datetime object."""
return parse(date_str)
def calculate_future_date(start_date: datetime) -> datetime:
"""Calculates a future date using relativedelta."""
# Add 1 month and move to the 1st Monday
return start_date + relativedelta(months=1, weekday=MO(1))
current_time_str: str = "2024-03-28 10:30:00 UTC"
parsed_dt: datetime = process_date_string(current_time_str)
print(f"Parsed datetime: {parsed_dt}")
future_dt: datetime = calculate_future_date(parsed_dt)
print(f"Future datetime: {future_dt}")
# Example where type checker would catch an error (uncomment to test):
# def expects_string(s: str):
# print(s)
# expects_string(123) # Mypy would report: Argument 's' to 'expects_string' has incompatible type "int"; expected "str"