{"id":591,"library":"types-python-dateutil","title":"Typing stubs for python-dateutil","description":"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.","status":"active","version":"2.9.0.20260323","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","dateutil","datetime","typeshed"],"install":[{"cmd":"pip install types-python-dateutil","lang":"bash","label":"Install stubs"}],"dependencies":[{"reason":"Provides typing stubs for this runtime library.","package":"python-dateutil","optional":false}],"imports":[{"symbol":"parse","correct":"from dateutil.parser import parse"},{"symbol":"relativedelta","correct":"from dateutil.relativedelta import relativedelta"},{"symbol":"tz","correct":"from dateutil import tz"},{"note":"As of python-dateutil 2.8.1, tz.UTC is preferred over tz.tzutc() for internal consistency and avoiding an unnecessary function call.","wrong":"from dateutil.tz import tzutc()","symbol":"UTC","correct":"from dateutil.tz import UTC"}],"quickstart":{"code":"from datetime import datetime\nfrom dateutil.parser import parse\nfrom dateutil.relativedelta import relativedelta, MO\n\n# Enable type checking in your editor or via a tool like Mypy\n# E.g., run `mypy your_script.py`\n\ndef process_date_string(date_str: str) -> datetime:\n    \"\"\"Parses a date string and returns a datetime object.\"\"\"\n    return parse(date_str)\n\ndef calculate_future_date(start_date: datetime) -> datetime:\n    \"\"\"Calculates a future date using relativedelta.\"\"\"\n    # Add 1 month and move to the 1st Monday\n    return start_date + relativedelta(months=1, weekday=MO(1))\n\ncurrent_time_str: str = \"2024-03-28 10:30:00 UTC\"\nparsed_dt: datetime = process_date_string(current_time_str)\nprint(f\"Parsed datetime: {parsed_dt}\")\n\nfuture_dt: datetime = calculate_future_date(parsed_dt)\nprint(f\"Future datetime: {future_dt}\")\n\n# Example where type checker would catch an error (uncomment to test):\n# def expects_string(s: str):\n#     print(s)\n# expects_string(123) # Mypy would report: Argument 's' to 'expects_string' has incompatible type \"int\"; expected \"str\"\n","lang":"python","description":"This quickstart demonstrates basic usage of `dateutil.parser.parse` and `dateutil.relativedelta` with type annotations. Installing `types-python-dateutil` provides these annotations, allowing static type checkers to ensure correct usage of `python-dateutil` functions and classes."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly immediately after new `python-dateutil` releases"},{"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.","message":"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.","severity":"breaking","affected_versions":"All 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.","message":"`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.","severity":"gotcha","affected_versions":"<3.10"},{"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.","message":"The `python-dateutil` library is not installed or not found in the Python environment, leading to a `ModuleNotFoundError` when attempting to import `dateutil`.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:23:08.798Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the type stub package: `pip install types-python-dateutil`","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.","error":"error: Library 'python-dateutil' has no type annotations"},{"fix":"Install the type stub package: `pip install types-python-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.","error":"Cannot find implementation or library stub for module 'dateutil'"},{"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`","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.","error":"error: \"parser\" has no attribute \"isoparse\" [attr-defined]"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"2.9.0.20260508","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":null,"mem_mb":null,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}