Install & Compatibility
Where this runs
tested against v0.16.0 · 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.074s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.064s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Schema
✓ from voluptuous import Schema
Required
✓ from voluptuous import Required
Optional
✓ from voluptuous import Optional
All
✓ from voluptuous import All
Any
✓ from voluptuous import Any
Coerce
✓ from voluptuous import Coerce
In
✓ from voluptuous import In
Match
✓ from voluptuous import Match
Invalid
✓ from voluptuous import Invalid
This quickstart demonstrates how to define a schema with required and optional fields, apply various validators (type coercion, regex matching, range checks, custom lambdas), and handle validation errors. It shows how Voluptuous automatically coerces types and handles default values for missing optional fields.
from voluptuous import Schema, Required, Optional, All, Coerce, In, Match, Invalid
import datetime
# Define a schema for user data
user_schema = Schema({
Required('id'): All(Coerce(int), lambda n: n > 0, msg='ID must be a positive integer'),
Required('username', default='guest'): All(str, Match(r'^[a-zA-Z0-9_]+$'), msg='Invalid username'),
Optional('email'): All(str, Match(r'^[\w.-]+@[\w.-]+\.[a-zA-Z]{2,}$'), msg='Invalid email format'),
Optional('age', default=18): All(Coerce(int), In(range(18, 100)), msg='Age must be between 18 and 99'),
Optional('roles', default=['user']): [str],
'is_active': Coerce(bool),
Optional('created_at', default=lambda: datetime.datetime.now()): Coerce(datetime.datetime)
})
# Valid data example
valid_data = {
'id': '123',
'username': 'john_doe',
'email': 'john@example.com',
'age': 30,
'is_active': True
}
# Invalid data example
invalid_data = {
'id': 0,
'username': 'john doe',
'age': 'twenty',
'is_active': 'yes' # Coerce(bool) is lenient, will be True
}
# Validate data
try:
validated_data = user_schema(valid_data)
print("\n--- Valid Data Validation ---")
print("Original data:", valid_data)
print("Validated data:", validated_data)
print(f"Created at (default):") # validated_data['created_at']
print("\n--- Invalid Data Validation ---")
print("Original data:", invalid_data)
user_schema(invalid_data) # This will raise an Invalid exception
except Invalid as e:
print(f"Validation failed: {e}")
Errors
Common errors & fixes
voluptuous.MultipleInvalid: required key not provided @ data['field_name']
The input data is missing a key that was explicitly defined as `Required` in the schema.
fixProvide the missing key in the input data or change the schema's key definition from `Required` to `Optional` if the field is not mandatory.
voluptuous.MultipleInvalid: extra keys not allowed @ data['unexpected_key']
The input data contains a key that is not defined in the schema, and the schema does not allow unspecified keys by default.
fixRemove the unexpected key from the input data or configure the schema to allow extra keys by passing `extra=voluptuous.ALLOW_EXTRA` to the `Schema` constructor.
voluptuous.MultipleInvalid: expected a string for dictionary value @ data['field_name']
The value provided for a field in the input data does not match the expected data type or validator specified in the schema.
fixAdjust the input data's value to conform to the type or validation rule defined in the schema (e.g., provide a string instead of an integer), or modify the schema's validator.
voluptuous.SchemaError: 'Key(some_key, optional=False)' is not a valid element of the schema
A `Key` object (often created with `Required()` or `Optional()`) was incorrectly used directly as a dictionary value or element in the schema definition instead of as a dictionary key or within a validator.
fixWhen defining a dictionary schema, use `Key('some_key', required=True)` or `Key('some_key', default=some_value)` as the key in the schema dictionary (e.g., `{Key('some_key'): str}`). Upgrade
Version history
0.16.0latest on PyPI · released Dec 18, 2025
Audit
Dependencies
No dependency data recorded yet.