Install & Compatibility
Where this runs
tested against v1.3.8 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.144s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.128s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Validator
✓ from cerberus import Validator
This quickstart demonstrates defining a schema with various rules (type, length, required, regex, min/max, nullable). It then creates a Validator instance, validates a sample document, and prints success or error messages. It also includes an example of an invalid document to show error reporting.
from cerberus import Validator
schema = {
'name': {'type': 'string', 'minlength': 3, 'maxlength': 10, 'required': True},
'age': {'type': 'integer', 'min': 0, 'max': 99, 'nullable': True},
'email': {'type': 'string', 'regex': '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'}
}
document = {
'name': 'John Doe',
'age': 30,
'email': 'john.doe@example.com'
}
v = Validator(schema)
if v.validate(document):
print('Document is valid.')
print(f'Normalized document: {v.normalized(document)}')
else:
print('Document is invalid.')
print(f'Errors: {v.errors}')
# Example with an invalid document
invalid_document = {
'name': 'Jo',
'age': 150,
'city': 'New York' # Unknown field
}
if not v.validate(invalid_document):
print(f'Invalid document errors: {v.errors}')
Debug
Known issues
breakingStarting with Cerberus 1.3.0, the `allow_unknown` validator option (which controls whether unknown fields in a document are allowed) now defaults to `False`. Previously, it implicitly allowed unknown fields.fixIf your application relies on unknown fields being allowed, explicitly set `allow_unknown=True` when initializing the `Validator` (`v = Validator(schema, allow_unknown=True)`) or define `allow_unknown: True` in relevant schema rules.
affects: >=1.3.0
gotchaSince Cerberus 1.1, `type` schema rules are processed *before* `coerce` rules. This means type validation is performed on the original value, not the coerced value.fixBe aware of this order. If your intent is to validate the type *after* coercion, ensure your `coerce` rule correctly handles the initial type, or apply type validation in a custom rule that runs post-coercion if necessary.
affects: >=1.1.0
gotchaThe `required: True` and `nullable: True` schema rules are orthogonal. `required: True` means the key *must* exist in the document. `nullable: True` means that if the key exists, its value *can* be `None`.fixUnderstand the distinction: `{'field': {'required': True, 'nullable': False}}` requires the field and its value cannot be `None`. `{'field': {'required': False, 'nullable': True}}` makes the field optional, but if present, its value can be `None`. affects: All 1.x versions
Errors
Common errors & fixes
{'field_name': ['unknown field']}
A document being validated contains a key (field) that is not defined in the validation schema, and the `allow_unknown` option is set to `False` (which is the default behavior in Cerberus).
fixEither add the field to the schema definition, or explicitly set `allow_unknown=True` on the `Validator` instance or within the schema rules for that specific dictionary level. For example: `v = Validator(schema, allow_unknown=True)` or `schema = {'my_dict': {'type': 'dict', 'allow_unknown': True}}`. DocumentError: 'document is not a dict'
The Cerberus `Validator` expects the top-level document passed to its `validate()` method to be a dictionary (a mapping), but it received a list or another non-dictionary type.
fixEnsure that the `document` argument passed to `validator.validate()` is always a dictionary. If you need to validate a list of dictionaries, you should typically iterate over the list and validate each dictionary individually against a schema defined for a single item, or wrap the list in a dictionary (e.g., `{'items': my_list}`) and define a schema for the 'items' key. cerberus.schema.SchemaError: {'field_name': ['unknown rule']}
A rule specified within the validation schema is not recognized by Cerberus, either due to a typo in the rule name, an attempt to use an unsupported rule, or a custom validation rule that has not been properly registered with a custom `Validator` subclass. This can also occur if a schema itself is malformed, such as expecting a dictionary for a schema definition but receiving a non-dictionary value.
fixReview the schema for typos in rule names. If using a custom rule, ensure it is correctly defined within a custom `Validator` class and that an instance of this custom `Validator` is used. If the `SchemaError` points to a malformed schema structure, correct the schema's type or nested structure.
Validator.validate() returns False but no exception is raised / how to get errors
By design, Cerberus does not raise exceptions for most validation failures. Instead, the `validate()` method returns `False` if validation fails, and all encountered errors are collected and stored in the `validator.errors` attribute.
fixAfter calling `validator.validate(document)`, always check its boolean return value. If `False`, access the `validator.errors` attribute to retrieve a dictionary containing detailed messages about all validation issues found in the document. For example: `v = Validator(schema); if not v.validate(document): print(v.errors)`.
Upgrade
Version history
1.3.8latest on PyPI · released Nov 6, 2025
Audit
Dependencies
No dependency data recorded yet.