pypi / pandas-stubs

pandas-stubs

What changed in pandas-stubs 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-29.

3 breaking37 deprecations7 new APIs and options2 performance22 behavior and defaults1 tooling16 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.9 on npm

pandas-stubs 387 changes

Breaking changes 3

The default for allow_duplicates changed from lib.no_default to False.
3.1.0docs
query raises ValueError when expr refers to a non-unique column label and still evaluates to a DataFrame, because no row mask is available.
3.1.0docs
The new stack implementation is the default as of pandas 3.0; with future_stack=True, dropna and sort have no impact and must remain unspecified.
3.0.0docs

Deprecations 37

The JSON-reading option is deprecated; parse date columns with to_datetime() after reading.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0.
3.1.0docs
Passing a dict as data is deprecated; use the DataFrame constructor or DataFrame.from_dict() instead.
3.1.0docs
Deprecates lsuffix in favor of suffixes.
3.1.0docs
Deprecates rsuffix in favor of suffixes.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0.
3.1.0docs
The verify_integrity keyword is deprecated; check result.index.is_unique directly instead.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0.
3.1.0docs
The 'fastparquet' and 'auto' engine options are deprecated; use 'pyarrow' or omit engine to use the default.
3.1.0docs
The dropna keyword is deprecated in to_hdf(), HDFStore.put(), HDFStore.append(), and HDFStore.append_to_multiple(); drop rows with DataFrame.dropna() before writing.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0.
3.1.0docs
The option is deprecated; use DataFrame.dropna() before writing instead.
3.1.0docs
The JSON-reading option is deprecated; parse date columns with to_datetime() after reading.
3.1.0docs
The default engine for xlsx/xlsm files will change from openpyxl to calamine in a future version; pass engine explicitly or set the reader option to retain current behavior.
3.1.0docs
The convert_boolean keyword is deprecated and will be removed in a future version.
3.1.0docs
The convert_floating keyword is deprecated and will be removed in a future version.
3.1.0docs
The convert_integer keyword is deprecated and will be removed in a future version.
3.1.0docs
The convert_string keyword is deprecated and will be removed in a future version.
3.1.0docs
The infer_objects keyword is deprecated and will be removed in a future version.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0; its displayed default changes from False to <no_default>.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0; its signature default changes from False to <no_default>.
3.1.0docs
The inplace keyword is deprecated since pandas 3.1.0 and will be removed in pandas 4.0.
3.1.0docs
Selecting labels with items will be deprecated; use DataFrame.select() when all items are present in the columns, or an intersection with .loc otherwise.
3.1.0docs
Selecting labels with like will be deprecated; the notes recommend filtering labels with a callable and str.contains instead.
3.1.0docs
Selecting labels with regex will be deprecated; the notes recommend filtering labels with a callable and str.contains instead.
3.1.0docs
Passing a non-dict to from_dict is deprecated; use the DataFrame constructor instead.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0.
3.1.0docs
The inplace keyword is deprecated in 3.1.0 and will be removed in pandas 4.0.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0.
3.1.0docs
The inplace keyword is deprecated and will be removed in pandas 4.0; its default is now shown as <no_default>.
3.1.0docs
The dropna keyword is deprecated; call DataFrame.dropna() before writing instead.
3.1.0docs
The engine emits a deprecation warning and will be removed in a future version; use calamine instead.
3.1.0docs
All float precision modes now use the same converter; float_precision is deprecated and will be removed in a future version.
3.1.0docs docs docs
The engine emits a deprecation warning and will be removed in a future version; use calamine instead.
3.1.0docs
The dropna parameter is deprecated since pandas 3.0 and will be removed in a future version.
3.0.0docs
The future_stack parameter is deprecated since pandas 3.0 and will be removed in a future version.
3.0.0docs
The sort parameter is deprecated since pandas 3.0 and will be removed in a future version.
3.0.0docs

New APIs and options 7

Accepts a boolean mask, callable, or pandas.col() expression through cond to filter rows or columns; masks align on the index or must match its length.
3.1.0docs
Adds a method to select columns by labels or expressions and create computed columns with keyword arguments; it always returns a DataFrame.
3.1.0docs
This option caps or disables parallel parsing of sufficiently large local uncompressed files read with the C engine.
3.1.0docs docs
Adds cond for filtering with a boolean mask, callable, or expression; expressions are supported only with axis=0.
3.1.0docs
Adds na to determine how missing values in a boolean mask are treated: False by default, True to keep them, or "raise" to raise a ValueError.
3.1.0docs docs
Accepts a boolean mask, callable, or pandas.col() expression through cond to filter rows; masks align on the index or must match its length.
3.1.0docs
Adds na to control missing values in the mask: they are False by default, can be kept with True, or raise an error with "raise".
3.1.0docs

Performance 2

Eligible large local files read with the C engine are split into chunks and parsed in multiple threads automatically; results match a serial read.
3.1.0docs
The C engine reads sufficiently large files in parallel; the pyarrow engine is multithreaded.
3.1.0docs docs

Behavior and default changes 21

The calamine engine supports Excel formats; it becomes the default for xls and xlsb when the corresponding legacy engine is not installed.
3.1.0docs
The default for inplace changed from False to <no_default>.
3.1.0docs
The inplace parameter's documented default changes from False to <no_default>.
3.1.0docs
The inplace default changes from False to <no_default>.
3.1.0docs
The freq of a DatetimeIndex or TimedeltaIndex is lost when it is inserted as a column and is not restored by a subsequent DataFrame.set_index().
3.1.0docs
The default for inplace changed from False to <no_default>.
3.1.0docs
The documented default for convert_boolean changes from True to <no_default>.
3.1.0docs
The documented default for convert_floating changes from True to <no_default>.
3.1.0docs
The documented default for convert_integer changes from True to <no_default>.
3.1.0docs
The documented default for convert_string changes from True to <no_default>.
3.1.0docs
The documented default for infer_objects changes from True to <no_default>.
3.1.0docs
The documented default for inplace changed from False to <no_default>.
3.1.0docs
The inplace parameter default changes from False to <no_default>.
3.1.0docs
The inplace parameter default changed from False to <no_default>.
3.1.0docs
Appending requires an existing object at key to use table format and requires exactly the same columns in the same order; creating a key with append=True defaults format to table.
3.1.0docs docs
Passing complib without complevel greater than 0 emits a UserWarning and writes the data uncompressed.
3.1.0docs
The dropna default changed from None to <no_default>.
3.1.0docs
The delimiter default is now <no_default> instead of None.
3.1.0docs
The delimiter default is now <no_default> instead of None.
3.1.0docs
With dtype="category", numeric and boolean categories are inferred; values that do not all parse as numeric or boolean retain string categories.
3.1.0docs
When chunks infer the same literal as different types, the concatenated column has object dtype, comparisons match only rows with the corresponding representation, and a DtypeWarning is emitted.
3.1.0docs docs

Tooling 1

The default axis is the index for boolean masks and the info axis (columns for a DataFrame) when selecting labels; expressions support only the index.
3.1.0docs

Fixes and other changes 16

Labels read from a header row are always strings; use names with header=0 to supply labels of another type.
3.1.0docs
A DatetimeIndex or TimedeltaIndex created from a column has freq=None; passing the index directly as keys keeps its freq.
3.1.0docs
Sorting is deterministic for a given input; mergesort and stable preserve equal-key order, and kind is ignored for MultiIndex sorting or when a level is specified.
3.1.0docs
The path can be a URL using schemes such as http, ftp, s3, gs, and file; some schemes require additional packages such as s3fs for S3.
3.1.0docs
Specifying dtype does not change missing-value parsing; recognized missing values remain NaN or the dtype's NA value.
3.1.0docs
A file-like object's read method must accept an optional size argument.
3.1.0docs
The documentation clarifies accepted header values, indexing, and how names interacts with header inference and overriding.
3.1.0docs
Files written by to_hdf use a pandas-specific layout and are intended for pandas read_hdf() or HDFStore, not as a general-purpose interchange format for arbitrary HDF5 consumers.
3.1.0docs
Duplicate index values are not considered when dropping duplicate rows; use Index.duplicated() with boolean indexing to drop rows with duplicate index labels.
3.1.0docs
The positional argument is a mask when it is a callable or expression; other list-like values select labels. A positional list of booleans selects labels and emits a warning.
3.1.0docs
The documentation states that sorting is deterministic for a given input and that mergesort and stable preserve the relative order of equal keys.
3.1.0docs
nan_rep is a string used only for missing values in string columns with table format; its default avoids collisions, while a supplied value is interpreted as missing and later appends reuse the table's stored representation.
3.1.0docs
The documentation lists quoting values 0 through 3 and explains their corresponding csv constants.
3.1.0docs
Converters receive raw text, including empty fields as empty strings; missing-value settings are applied to the returned value.
3.1.0docs docs
S3 URLs require the s3fs library.
3.1.0docs
Some URL schemes may require additional packages; for example, S3 URLs require s3fs.
3.1.0docs

pandas-stubs 21 changes

Behavior and default changes 1

Copy-on-Write is the default with pandas 3.0; it prevents one statement from updating multiple objects and can improve average performance and memory usage by delaying copies.
2.0.0docs