pandas-stubs

3.0.0.260204 verified Tue May 12 auth: no python install: stale quickstart: stale

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.

pip install pandas-stubs

Common errors

error Library stubs not installed for "pandas" [import] ↓

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.

fix

Install pandas-stubs using pip: pip install pandas-stubs or mypy --install-types to automatically install missing stubs.

error Argument "decimals" to "round" of "DataFrame" has incompatible type "DataFrame"; expected "Union[int, Dict[Any, Any], Series]" ↓

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.

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})

error Missing type parameters for generic type "Series" ↓

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.

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).

error Incompatible types in assignment (expression has type "Series[Any]", variable has type "Series[float]") ↓

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]`.

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].

Warnings

breaking 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

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.

breaking 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. ↓

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.

breaking 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. ↓

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.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

pandas
wrong
```
from pandas_stubs import DataFrame
```
correct
```
import pandas as pd
```
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.

Quickstart stale last tested: 2026-04-23

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.

import pandas as pd

def analyze_data(df: pd.DataFrame) -> pd.Series:
    # This operation is correctly typed
    total_sales = df['sales'].sum()
    print(f"Total sales: {total_sales}")
    
    # Example that would cause a type error with pandas-stubs
    # pandas.DataFrame.round expects a Series or int for 'decimals', not another DataFrame.
    # This line is commented out to allow the script to run without runtime error, 
    # but a type checker would flag it.
    # decimals_df = pd.DataFrame({'price': 2})
    # df_rounded = df.round(decimals=decimals_df)

    # Correct usage for .round() method
    decimals_series = pd.Series({'price': 2, 'quantity': 0})
    df['price'] = df['price'].round(decimals=decimals_series.get('price', 0))
    return df['price']

if __name__ == "__main__":
    data = {'item': ['A', 'B', 'C'], 'sales': [100.5, 150.2, 200.0], 'price': [10.234, 5.678, 12.345], 'quantity': [10, 20, 15]}
    sales_df = pd.DataFrame(data)
    processed_prices = analyze_data(sales_df)
    print(processed_prices)