{"id":550,"library":"pandas-stubs","title":"pandas-stubs","description":"pandas-stubs provides public type annotations for the pandas library, adhering to PEP 561 for separate stub packages. These stubs enable static type checking of pandas code, focusing on recommended usage patterns and aiming for soundness over completeness. The current version, 3.0.0.260204, indicates a test against pandas 3.0.0, with stub releases occurring more frequently than pandas releases to reflect ongoing type evolution.","status":"active","version":"3.0.0.260204","language":"python","source_language":"en","source_url":"https://github.com/pandas-dev/pandas-stubs","tags":["typing","stubs","type-hints","pandas","data-science"],"install":[{"cmd":"pip install pandas-stubs","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"The stubs provide type information for the `pandas` library, which must be installed for the stubs to be useful.","package":"pandas","optional":false},{"reason":"Listed as a required dependency for pandas-stubs itself on PyPI.","package":"numpy","optional":false},{"reason":"A static type checker commonly used with pandas-stubs to perform type analysis.","package":"mypy","optional":true}],"imports":[{"note":"pandas-stubs is a stub-only package (PEP 561). Its `.pyi` files are automatically discovered and used by type checkers like MyPy when `pandas` is imported; direct imports from `pandas_stubs` are not intended for runtime use.","wrong":"from pandas_stubs import DataFrame","symbol":"pandas","correct":"import pandas as pd"}],"quickstart":{"code":"import pandas as pd\n\ndef analyze_data(df: pd.DataFrame) -> pd.Series:\n    # This operation is correctly typed\n    total_sales = df['sales'].sum()\n    print(f\"Total sales: {total_sales}\")\n    \n    # Example that would cause a type error with pandas-stubs\n    # pandas.DataFrame.round expects a Series or int for 'decimals', not another DataFrame.\n    # This line is commented out to allow the script to run without runtime error, \n    # but a type checker would flag it.\n    # decimals_df = pd.DataFrame({'price': 2})\n    # df_rounded = df.round(decimals=decimals_df)\n\n    # Correct usage for .round() method\n    decimals_series = pd.Series({'price': 2, 'quantity': 0})\n    df['price'] = df['price'].round(decimals=decimals_series.get('price', 0))\n    return df['price']\n\nif __name__ == \"__main__\":\n    data = {'item': ['A', 'B', 'C'], 'sales': [100.5, 150.2, 200.0], 'price': [10.234, 5.678, 12.345], 'quantity': [10, 20, 15]}\n    sales_df = pd.DataFrame(data)\n    processed_prices = analyze_data(sales_df)\n    print(processed_prices)","lang":"python","description":"To use `pandas-stubs`, first install `pandas`, `pandas-stubs`, and a type checker like `mypy`. Then, write your pandas code as usual. Run `mypy your_script.py` to check for type errors. The example demonstrates a common DataFrame operation and comments out an incorrect usage of `DataFrame.round()` that `pandas-stubs` would catch, along with its correct version."},"warnings":[{"fix":"Consult the official pandas-stubs GitHub issue tracker (specifically issue #1654 and #1641) for ongoing compatibility updates and known limitations when working with pandas 3.0 and newer.","message":"The current 3.0.x releases of pandas-stubs may not fully support all new features introduced in pandas 3.0. This can lead to unexpected type errors or missing type information for newer APIs.","severity":"breaking","affected_versions":"pandas-stubs 3.0.x for pandas 3.0.x"},{"fix":"When encountering unexpected type errors, first review the pandas documentation for the recommended usage. If the code is intentionally flexible, consider adding `type: ignore` comments for specific lines or sections, or consult the pandas-stubs philosophy documentation.","message":"pandas-stubs provides a 'narrower' set of type annotations compared to what pandas itself might allow, prioritizing recommended best practices and soundness over complete API coverage. This means some valid pandas code, especially less common patterns, might still raise type errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For type checking your application code, prioritize the types provided by `pandas-stubs`. If encountering discrepancies, refer to the `pandas-stubs` repository for public API typing.","message":"The typing goals for `pandas` itself (internal consistency) and `pandas-stubs` (public API usage) differ. This can occasionally lead to inconsistencies or divergences in type definitions between the two projects. While a long-term goal is to merge them, they remain separate for now.","severity":"gotcha","affected_versions":"All versions"},{"fix":"After updating `pandas` or `pandas-stubs`, run your type checker and review any new errors. Adjust your code to align with the updated type signatures or, if necessary, use type ignores (`# type: ignore`) for known legitimate patterns that the stubs might not yet fully cover.","message":"Changes in pandas API or updates to pandas-stubs (e.g., how methods like `itertuples()` are typed) can introduce new type checker errors in existing code that previously passed without issue.","severity":"gotcha","affected_versions":"All versions, especially after updates to pandas or pandas-stubs"},{"fix":"Ensure `pandas` is installed in your Python environment by running `pip install pandas`. If using a virtual environment, activate it before installation. Also, verify that your script is being executed with the Python interpreter where `pandas` is installed.","message":"The `pandas` library was not found in the environment, leading to a `ModuleNotFoundError`. This typically occurs when `pandas` has not been installed via pip or is not available in the active Python environment.","severity":"breaking","affected_versions":"All versions of pandas and pandas-stubs"},{"fix":"Ensure `pandas` is correctly installed in the Python environment using `pip install pandas` or verify your virtual environment/container setup. The output also suggests updating pip and using a virtual environment, which is good practice for managing dependencies.","message":"The `pandas` library is not found in the environment. This error occurs when the `pandas` package has not been installed or is not accessible in the current Python interpreter's path.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T15:00:49.050Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install pandas-stubs using pip: `pip install pandas-stubs` or `mypy --install-types` to automatically install missing stubs.","cause":"Mypy cannot find the type information for the pandas library because the separate pandas-stubs package has not been installed or is not correctly configured in your environment.","error":"Library stubs not installed for \"pandas\" [import]"},{"fix":"Ensure the `decimals` argument is of the correct type, for example, convert the DataFrame to a Series: `decimals = pd.Series({'TSLA': 2, 'AMZN': 1})`","cause":"You are passing a `pandas.DataFrame` object to the `round` method's `decimals` argument, but pandas-stubs expects either an `int`, a `dict`, or a `pandas.Series` for this parameter.","error":"Argument \"decimals\" to \"round\" of \"DataFrame\" has incompatible type \"DataFrame\"; expected \"Union[int, Dict[Any, Any], Series]\""},{"fix":"Specify the type parameter for the generic, for example: `my_series: pd.Series[float]` or `my_dataframe: pd.DataFrame[MySchema]` (if using `pandera.typing.DataFrame`).","cause":"You are using a generic type like `pd.Series` or `pd.DataFrame` without specifying the type of its contents, which is required by static type checkers like Mypy when strict type checking is enabled.","error":"Missing type parameters for generic type \"Series\""},{"fix":"You can either explicitly cast the expression to the desired type using `typing.cast(pd.Series[float], expression)` or refine the preceding operations to ensure Mypy can infer the correct, more specific type. If `Any` is acceptable for a specific line, you can add `# type: ignore[assignment]`.","cause":"Mypy has inferred the type of an expression as `Series[Any]` (often due to an operation where specific type information is not available or explicitly lost), but you are attempting to assign it to a variable explicitly typed as a more specific `Series[float]`.","error":"Incompatible types in assignment (expression has type \"Series[Any]\", variable has type \"Series[float]\")"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"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":"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":"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":"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":"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":"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":"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":"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":"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":"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":"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}]}}