Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Performance and Patterns

Pydantic Performance Tips

Make Pydantic fast. Learn validate_json, reusing TypeAdapter, tagged unions, avoiding repeated validation, model_construct, strict mode and how to measure before tuning.

Pydantic v2 is already fast: its validation and serialization run in a compiled Rust library called pydantic-core. For most programs you never need to think about speed. When you validate millions of records, serve a busy API or load large files, a few habits make a real difference. This lesson lists them in rough order of payoff, and shows how to measure so you tune what matters.

The timings printed by the examples depend on your computer and on this browser runtime, which is slower than a normal server. Compare the ratios between two lines, not the absolute numbers.

Measure first

Use time.perf_counter() around a loop, or timeit. A small helper keeps examples honest:

Python A tiny benchmark helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Taking the minimum of several runs filters out noise from other processes. Use the same helper in the next examples.

1. Validate JSON directly

If your data starts as JSON text or bytes, call model_validate_json (or TypeAdapter.validate_json). It parses and validates together in Rust. Doing json.loads first and model_validate second creates a whole Python object tree only to read it again.

Python model_validate_json versus loads + validate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

2. Create adapters and models once

A class definition and a TypeAdapter(...) build a validator, which is relatively slow (milliseconds). Define them at module level. A common slip is writing TypeAdapter(list[int]) inside a function that runs on every request.

Python Adapter built once versus every call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

3. Use tagged (discriminated) unions

A plain union such as Cat | Dog | Bird tries each member in turn and collects errors from all that fail, which is slow and gives long error messages. A discriminated union names a field (the tag) that selects the member immediately. It is faster and its errors are short and precise.

Python Discriminated union

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Only the Dog branch is tried, so the error list has one entry that points at good_boy.

4. Avoid validating twice

Every Model(**data) call validates. Passing an existing model instance into another model does not revalidate it by default (revalidate_instances="never"), which is fast, but code that rebuilds objects Model(**obj.model_dump()) repeats work and creates copies. Prefer passing the object itself, or model_copy(update={...}) for a changed copy.

Python Skipping needless revalidation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note that model_copy(update=...) does not validate the new value. That is the trade-off: speed for responsibility.

5. model_construct for trusted data

Model.model_construct(**values) creates an instance without validation. It is much faster, and it is safe only when the data is already known to be valid, for example rows you just wrote yourself. With bad data you get an object that quietly violates its own types.

Python model_construct skips checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Treat model_construct as an optimization of last resort, applied after a profile shows validation is the bottleneck and the input is trusted.

6. Smaller models and simpler types

  • Every field and every validator costs time; do not declare fields you never read (use extra="ignore", the default).
  • Python-function validators (field_validator, AfterValidator) call back into Python for each value. Built-in constraints (ge, max_length, pattern) run in Rust and are faster. Prefer constraints when they can express the rule.
  • Use strict=True where you control the input; skipping coercion removes some work.
  • list[int] is fast; a Sequence[int] or Any can be slower or skip checks.
  • Use TypedDict or a plain dataclass through TypeAdapter if you do not need model features. They can be cheaper to construct.

7. Serialize efficiently

model_dump_json() writes JSON straight from Rust and is faster than json.dumps(model.model_dump()). For lists of models wrap them in a TypeAdapter(list[Model]) and call dump_json.

Python model_dump_json versus json.dumps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

8. Work in batches and stream large inputs

Validating a million rows in one call needs memory for all of them. For big files, read and validate in chunks (for example 10,000 rows at a time) and write results as you go. The CSV project in this track does this.

flowchart LR
    F["large file"] --> C["read a chunk"]
    C --> V["validate chunk<br/>(TypeAdapter)"]
    V --> O["write valid rows"]
    V --> R["collect errors"]
    O --> C

Chunking keeps memory flat and lets you report errors as you go.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You receive JSON text. Which call is usually fastest?

    model_validate_json parses and validates in one pass in the Rust core, avoiding an intermediate Python structure.
  2. 2. Why use a discriminated union?

    A plain union tries every member in turn. A discriminator selects one immediately.
  3. 3. When is model_construct appropriate?

    It skips validation entirely, so bad data produces inconsistent objects without any error.
  4. 4. What is the first step before optimizing?

    Most programs never need tuning; measurement tells you where time actually goes.

Summary

  • Measure with perf_counter or timeit; compare ratios.
  • Use validate_json and dump_json, create models and adapters once at module level.
  • Prefer discriminated unions, built-in constraints over Python validators, and strict=True where input is controlled.
  • Use model_construct only for trusted data; avoid pointless revalidation and copies.
  • Process large inputs in chunks.

Next: Generics and Recursive Models