---
id: voluptuous
version: "0.16.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# voluptuous — Python data validation library

License: permissive · Maintenance: active · Downloads: 6.9M/mo

## What it is and what it does

Voluptuous is a Python data validation library designed to check incoming data (from JSON, YAML, APIs, etc.) against a schema you define. Rather than writing custom validation code, you describe your data structure using simple Python types and callables—dictionaries, lists, type checks, and custom validators—and Voluptuous matches input against that schema, raising detailed exceptions when validation fails.

The library prioritizes simplicity and useful error messages. Schemas are just Python data structures: `{int: str}` means a dict with integer keys and string values, `[int, float, str]` means a list containing only those types. You can nest schemas arbitrarily and compose validators using functions like `Required`, `All`, `Range`, and `Length`. When validation fails, you get a clear path to the problem in your data.

Use it for:

- Validate API request parameters before processing them in a web service.
- Check configuration files (JSON/YAML) match expected structure at application startup.
- Enforce data contracts in data pipelines before passing records downstream.
- Validate form submissions or user input in web applications.
- Ensure nested data structures from external sources conform to expected types and constraints.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Voluptuous validates Python data structures (dictionaries, lists, nested objects) against declarative schemas, raising detailed exceptions when data doesn't match.

Yes, if you need straightforward schema validation for structured data. Voluptuous is stable, has no dependencies, and is widely used. The contributions-only maintenance model is a trade-off: expect community-driven fixes and no proactive feature work, but the core library is mature and unlikely to need frequent changes. Choose it if you prefer declarative schemas over class-based validators.

## Install

pip install voluptuous
uv add voluptuous
poetry add voluptuous

## Installing voluptuous

Before you install: Low friction—pure Python wheel with no runtime dependencies. Actively maintained with recent releases; however, the maintainer has stated the project is in contributions-only mode and no longer uses it personally, so expect community-driven fixes rather than proactive feature development.

License in practice: BSD-3-Clause is permissive; you may use, modify, and distribute voluptuous freely in commercial and open-source projects with minimal restrictions.

Quickstart:

pip install voluptuous

from voluptuous import Schema, Required, All, Range

schema = Schema({
    Required('q'): str,
    'per_page': All(int, Range(min=1, max=20)),
})

result = schema({'q': 'search term', 'per_page': 10})

Requires Python 3.9 or later.

Verify before relying:

- Performance characteristics on very large or deeply nested data structures.
- Extent of community support and PR review turnaround given contributions-only status.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python data validation library, schema validation json yaml, validate nested data structures, input validation with error messages, declarative schema validation, python dict validation, structured data validation, validation, schema, data-validation

[View on SkillFed](https://skillfed.io/packages/voluptuous) · [View on PyPI](https://pypi.org/project/voluptuous/)