Install & Compatibility
Where this runs
tested against v2.7.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.072s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.070s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
convert
✓ from voluptuous_serialize import convert
The main function to serialize a voluptuous schema.
vol
✓ import voluptuous as vol
Standard import alias for creating voluptuous schemas.
This quickstart demonstrates how to define a `voluptuous` schema and then use `voluptuous-serialize.convert` to transform it into a dictionary representation. The output is a list of dictionaries, each describing a field in the schema, including its name, type, and validation rules.
import voluptuous as vol
from voluptuous_serialize import convert
schema = vol.Schema({
vol.Required("name"): vol.All(str, vol.Length(min=5)),
vol.Required("age"): vol.All(vol.Coerce(int), vol.Range(min=18)),
vol.Optional("email", default=""): str,
vol.Optional("tags", default=[]): [str]
})
serialized_schema = convert(schema)
print(serialized_schema)
# Example of output structure (simplified):
# [
# {'name': 'name', 'type': 'string', 'lengthMin': 5, 'required': True},
# {'name': 'age', 'type': 'integer', 'valueMin': 18, 'required': True},
# {'name': 'email', 'type': 'string', 'default': '', 'required': False},
# {'name': 'tags', 'type': 'array', 'items': {'type': 'string'}, 'default': [], 'required': False}
# ]
Debug
Known issues
deprecatedThe use of `"optional": true` within schema definitions is deprecated. Users should instead rely on the `"required"` key to indicate optional fields (i.e., `"required": false`).fixReplace `vol.Optional('key', optional=True)` or schema outputs containing `"optional": true` with `vol.Optional('key')` which results in `"required": false` in the serialized output. affects: All versions where 'required' key is the preferred method (explicitly mentioned in 2.7.0 docs).
gotchaThe library's GitHub README explicitly states it's for 'internal use of HA only' (Home Assistant). While usable by others, this suggests development priorities may align specifically with Home Assistant's needs, potentially leading to design choices or breaking changes that prioritize HA compatibility over general-purpose use cases.fixBe aware that external use might require monitoring updates closely for HA-specific changes. Consider if your use case aligns with the implicit design goals of a library primarily maintained for another project.
affects: All versions, as this is a stated intent/scope.
gotchaThe upstream `voluptuous` library, which `voluptuous-serialize` depends on, is in 'CONTRIBUTIONS ONLY' mode, as stated on its GitHub page. This implies that the original author is no longer actively fixing issues or adding features, relying solely on community pull requests. This could impact the long-term stability and responsiveness to bugs in the underlying validation logic.fixUsers should be aware of the upstream maintenance status. Report issues to both `voluptuous-serialize` and, if applicable, directly to the `voluptuous` project, and consider contributing fixes if critical issues arise.
affects: All versions, due to upstream dependency status.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'voluptuous_serialize'
The `voluptuous-serialize` package is not installed in the current Python environment or is not accessible on the Python path.
fixpip install voluptuous-serialize
AttributeError: module 'voluptuous_serialize' has no attribute 'serialize'
The main function provided by the `voluptuous-serialize` library to convert a schema is `convert_schema`, not `serialize`.
fixfrom voluptuous_serialize import convert_schema
'dict' object has no attribute 'schema'
The `convert_schema` function expects an actual `voluptuous.Schema` object, not a plain Python dictionary that defines a schema.
fiximport voluptuous as vol
from voluptuous_serialize import convert_schema
my_vol_schema = vol.Schema({"name": str, vol.Optional("age"): int})
serialized_schema = convert_schema(my_vol_schema) Upgrade
Version history
2.7.0latest on PyPI · released Aug 17, 2025
Audit
Dependencies
voluptuousrequiredCore dependency for defining schemas that voluptuous-serialize converts.