Skip to main content

Getting Started

pydantic-core provides the high-performance core functionality for Pydantic validation and serialization. While most users should interact with it through the main Pydantic library, it can be used directly for maximum performance.

Prerequisites​

  • Python: version 3.10 or newer.
  • Rust: Required only if building from source (stable or nightly).
  • uv: Recommended for fast dependency management and development.

Installation​

The easiest way to install pydantic-core is via pip:

pip install pydantic-core

Building from Source​

If you are contributing to the project or need a development build, you can use the provided Makefile:

# Clone the repository
git clone https://github.com/pydantic/pydantic-core.git
cd pydantic-core

# Install dependencies and build the development version
make install

Hello World / Quick Start​

pydantic-core uses a schema-based approach to validation. You define a schema as a Python dictionary and use SchemaValidator to validate data against it.

from pydantic_core import SchemaValidator, ValidationError

# Define a schema for a simple user profile
v = SchemaValidator(
    {
        'type': 'typed-dict',
        'fields': {
            'name': {
                'type': 'typed-dict-field',
                'schema': {'type': 'str'},
            },
            'age': {
                'type': 'typed-dict-field',
                'schema': {
                    'type': 'int',
                    'ge': 18,
                },
            },
            'is_active': {
                'type': 'typed-dict-field',
                'schema': {
                    'type': 'default',
                    'schema': {'type': 'bool'},
                    'default': True,
                },
            },
        },
    }
)

# Validate Python data
data = {'name': 'Alice', 'age': 30}
result = v.validate_python(data)
print(result)
# Output: {'name': 'Alice', 'age': 30, 'is_active': True}

# Validate JSON directly (faster than json.loads + validate_python)
json_data = '{"name": "Bob", "age": 25}'
result_json = v.validate_json(json_data)
print(result_json)

# Handle validation errors
try:
    v.validate_python({'name': 'Charlie', 'age': 16})
except ValidationError as e:
    print(e)

Verify Installation​

You can verify that pydantic-core is installed correctly by checking its version:

python -c "import pydantic_core; print(pydantic_core.__version__)"

Next Steps​

  • Pydantic Documentation: Most users should use the high-level Pydantic library.
  • Core Schema Reference: Explore pydantic_core/core_schema.py for all available schema types and configuration options.
  • Benchmarks: Check the tests/benchmarks/ directory in the repository to see performance comparisons.

Troubleshooting​

Missing Rust Compiler​

If you are installing from source and see errors related to cargo or maturin, ensure you have the Rust toolchain installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Type Hinting Issues​

pydantic-core uses a compiled extension. If your IDE is not showing completions, ensure you have typing-extensions installed and that your IDE supports .pyi stub files (like the one found at pydantic_core/_pydantic_core.pyi).