{"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":[{"wrong":"from dateutil.parser import parse","symbol":"parse","correct":"from dateutil-stubs.parser import parse"}],"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,"search_vec":"'2.9':64 '2.9.0.20260323':80 'accur':58 'aim':55 'allow':23 'annot':59 'catch':38 'checker':25 'code':32 'current':77 'daili':70 'datetim':86 'dateutil':6,10,20,37,63,85 'direct':71 'error':43 'frequent':68 'hint':84 'librari':21 'like':26 'mypi':27 'often':69 'packag':47 'part':49 'popular':17 'potenti':39 'project':53 'provid':11,57 'pyright':29 'python':5,9,19,36,62 'python-dateutil':4,18,35,61 'relat':42 'releas':67 'repositori':75 'runtim':45 'static':12 'stub':2,14,82 'type':1,8,13,24,41,81,83 'type-rel':40 'types-python-dateutil':7 'typesh':52,74,87 'updat':65 'use':34 'verifi':31 'version':78","created_at":"2026-03-28T15:20:24.981825+00:00","updated_at":"2026-04-16T23:43:01.828573+00:00","problems":{"verify_error":"File \"<string>\", line 1\n    from dateutil-stubs.parser import parse\n                 ^\nSyntaxError: invalid syntax"},"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"2.9.0.20260807","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/python-dateutil.md","pypi":"https://pypi.org/project/types-python-dateutil/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-27","next_check":"2026-07-10","install_tag":"stale"}}