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.
Install & Compatibility
Where this runs
tested against v2.3.3.260113 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pandas
✓ import pandas
✗ import pandas as pd
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)
Debug
Known issues
breakingThe 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.fixConsult 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.
affects: pandas-stubs 3.0.x for pandas 3.0.x
gotchapandas-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.fixWhen 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.
affects: All versions
gotchaThe 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.fixFor 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.
affects: All versions
gotchaChanges 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.fixAfter 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.
affects: All versions, especially after updates to pandas or pandas-stubs
breakingThe `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.fixEnsure `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.
affects: All versions of pandas and pandas-stubs
breakingThe `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.fixEnsure `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.
affects: All versions
Upgrade
Version history
3.0.3.260530latest on PyPI
Audit
Dependencies
pandasrequiredThe stubs provide type information for the `pandas` library, which must be installed for the stubs to be useful.
numpyrequiredListed as a required dependency for pandas-stubs itself on PyPI.
mypyoptionalA static type checker commonly used with pandas-stubs to perform type analysis.