Pandera is a lightweight and flexible open-source Python library for data validation and testing statistical data objects, such as Pandas DataFrames and Series. It allows users to define schema objects to validate the structure, types, and values of data, ensuring data quality and preventing unexpected errors. The library is actively maintained, with version 0.30.1 currently available, and undergoes frequent minor releases.
Install & Compatibility
Where this runs
tested against v0.31.1 · 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
py 3.10
14/15 runs
14/15 runs
py 3.11
14/15 runs
14/15 runs
py 3.12
14/15 runs
14/15 runs
py 3.13
14/15 runs
14/15 runs
py 3.9
9/15 runs
14/15 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pandera
✓ import pandera as pa
DataFrameSchema
✓ from pandera import DataFrameSchema
Column
✓ from pandera import Column
Check
✓ from pandera import Check
SeriesSchema
✓ from pandera import SeriesSchema
This quickstart defines a `DataFrameSchema` with column and index constraints, then demonstrates validating both a valid and an invalid Pandas DataFrame. It also shows how to catch `SchemaErrors` and inspect `failure_cases`.
import pandas as pd
import pandera as pa
from pandera import Column, DataFrameSchema, Check
# 1. Define a DataFrameSchema
schema = DataFrameSchema(
columns={
"id": Column(int, Check.greater_than_or_equal_to(0)),
"name": Column(str, Check.str_matches(r"^[A-Za-z]+$")),
"value": Column(float, Check.in_range(0.0, 1.0))
},
# Optionally specify index validation
index=pa.Index(int, name="index"),
# Ensure no extra columns exist
strict=True
)
# 2. Create a valid DataFrame
valid_df = pd.DataFrame({
"id": [1, 2, 3],
"name": ["Alice", "Bob", "Charlie"],
"value": [0.1, 0.5, 0.9]
})
# 3. Validate the DataFrame
try:
validated_df = schema.validate(valid_df)
print("Valid DataFrame validated successfully:")
print(validated_df)
except pa.errors.SchemaErrors as e:
print(f"Validation failed unexpectedly for valid data: {e}")
# 4. Create an invalid DataFrame to demonstrate error handling
invalid_df = pd.DataFrame({
"id": [-1, 2, 3], # Fails 'greater_than_or_equal_to(0)'
"name": ["Alice", "Bob1", "Charlie"], # Fails 'str_matches'
"value": [0.1, 0.5, 1.5], # Fails 'in_range'
"extra_col": [1, 2, 3] # Fails 'strict=True'
})
try:
schema.validate(invalid_df)
except pa.errors.SchemaErrors as e:
print("\nInvalid DataFrame caught by schema errors:")
print(e.failure_cases)
print(f"Total errors: {e.n_failures}")
Errors
Common errors & fixes
pandera.errors.SchemaError: <Schema Column(name=..., type=DataType(...))> failed element-wise validator ...
This is the most common error in Pandera, indicating that a DataFrame or Series failed to meet the validation constraints defined in its schema, such as incorrect data types, values out of range, or failing custom checks.
fixExamine the error message, specifically the 'failure cases', to identify which values or rows violated the schema. Adjust the data to conform to the schema or modify the schema if the data is intentionally different. Using `lazy=True` in `validate()` will collect all errors into a `SchemaErrors` exception, providing a comprehensive report of all failures instead of stopping at the first one.
AttributeError: 'dict' object has no attribute 'validate'
This error typically occurs when the `validate` method is called on a Python dictionary or another non-Pandera object, instead of a properly instantiated `DataFrameSchema`, `SeriesSchema`, or `DataFrameModel` object.
fixEnsure you are calling `.validate()` on an instance of a Pandera schema or model class. If you're using a dictionary to define your schema, you must pass it to `pa.DataFrameSchema()` first before calling `validate`.
pandera.errors.SchemaError: expected series 'column_name' to have type 'int64', got 'object'
This error often arises when an integer column contains or is expected to contain `NaN` (null) values. Pandas' `int64` dtype does not support `NaN`, so such columns are typically coerced to `float64` or `object` by Pandas, leading to a type mismatch with the `pandera` schema.
fixTo allow nulls in an integer column, explicitly set `nullable=True` in the `Column` definition and use a nullable integer type like `pd.Int64Dtype()` (available in pandas 0.24+) or `pandera.Int` from `pandera.typing`. Alternatively, use `float` if decimal values are acceptable.
pandera.errors.SchemaError: column 'column_name' not in dataframe
This error indicates that a column specified as `required` in the Pandera schema is missing from the DataFrame being validated. By default, all columns defined in a schema are considered required.
fixEither add the missing column to your DataFrame or mark the column as optional in your schema by using `pa.Column(..., required=False)` or, if using `DataFrameModel`, by annotating it with `typing.Optional`.
pandera.errors.SchemaError: SeriesSchema: did not expect column(s) ['unexpected_column']
This error occurs when the `strict=True` option is set in `DataFrameSchema` (or `DataFrameModel.Config`), which enforces that the DataFrame must contain *only* the columns explicitly defined in the schema. Any additional columns will trigger this error.
fixIf the unexpected columns should be allowed, remove `strict=True` from your schema definition. If the unexpected columns should be dropped, use `strict='filter'` in your schema. If they are truly errors, you must remove them from the DataFrame before validation.
Audit
Dependencies
pandasrequiredCore DataFrame validation backend
numpyrequiredUsed for numerical operations and type handling
polarsoptionalOptional backend for Polars DataFrame validation
pysparkoptionalOptional backend for PySpark DataFrame validation