Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Pydantic v2 vs dataclasses vs TypedDict: Speed and Memory

TypedDict validates nothing, a dataclass accepts the wrong type, and Pydantic pays for a compiled validator. A reproducible benchmark and where each belongs.

~5 min readPython
#Python#Pydantic#Performance#Data Modeling
3D illustration of three cubes on a balance scale, one with a validation shield, one with a speed arrow, one translucent

Introduction & Quick Summary

Symptom. A codebase has three ways to describe the same payload — a TypedDict for a JSON response, a @dataclass for an internal record, a Pydantic BaseModel at the API edge — and the performance discussion around them is folklore. Someone adds "just use dataclasses, Pydantic is slow", the next person benchmarks a BaseModel built from a dict and concludes validation costs 4× a dataclass, and a third points out the dataclass accepts {"id": "banana"} without complaint.

Cause. The three constructs are not competing implementations of one thing. TypedDict exists only for type checkers and produces a plain dict at runtime with zero overhead and zero validation. dataclass generates __init__, __repr__ and __eq__ and stores attributes, but ignores type hints at runtime: Point(x="1") is accepted. Pydantic v2 parses, coerces and validates into a model built by a compiled Rust core, which costs per-field work but gives you serialisation, JSON Schema and precise errors.

Fix. Choose by boundary: Pydantic at every edge where data is untrusted (HTTP requests, env vars, third-party JSON), dataclasses in hot internal code where the values are already validated, TypedDict for typing functions that pass dictionaries around without converting them. Benchmark with timeit on the shape you actually process, prefer model_validate_json() over json.loads() plus model_validate(), and skip validation deliberately with model_construct() only where you can prove the input.

Core Mechanics, Signatures & Reproducible Setup

The three differ in where work happens. TypedDict is erased at import: the function below is a dict at runtime and __annotations__ is all that remains. dataclass runs field processing at class creation and then a plain __init__ at instantiation; validation only happens if you write __post_init__. Pydantic builds a SchemaValidator per model, compiled once, and calls into it on each model_validate.

python
from dataclasses import dataclass, field from typing import TypedDict, NotRequired from pydantic import BaseModel, Field, ConfigDict import timeit class UserDict(TypedDict): id: int email: str tags: NotRequired[list[str]] @dataclass(frozen=True, slots=True) class UserDC: id: int email: str tags: list[str] = field(default_factory=list) class User(BaseModel): model_config = ConfigDict(extra="forbid") id: int email: str = Field(pattern=r"^[^@]+@[^@]+$") tags: list[str] = [] payload = {"id": 7, "email": "a@b.co", "tags": ["admin"]} assert User.model_validate(payload) == User(**payload) print(User.model_json_schema()["required"]) # ['id', 'email']

A benchmark worth trusting measures the whole boundary — parse text, validate, build — and repeats enough runs that the first-call import and JIT of the compiled core disappear from the average:

python
import json, timeit text = json.dumps(payload) * 1 setup = "from __main__ import User, UserDC, json, text" print("pydantic model_validate ", timeit.timeit("User.model_validate(json.loads(text))", setup, number=100_000)) print("pydantic model_validate_json ", timeit.timeit("User.model_validate_json(text)", setup, number=100_000)) print("pydantic model_construct ", timeit.timeit("User.model_construct(**json.loads(text))", setup, number=100_000)) print("dataclass(**dict) ", timeit.timeit("UserDC(**json.loads(text))", setup, number=100_000)) print("dict(**dict) ", timeit.timeit("dict(**json.loads(text))", setup, number=100_000)) print("json.loads only ", timeit.timeit("json.loads(text)", setup, number=100_000))

On CPython 3.13 with pydantic 2.10 the ordering is stable even though absolute numbers are not: json.loads and a plain dict at the bottom, a slotted frozen dataclass roughly 1.5–3× a plain dict, model_validate_json roughly 4–7× the dataclass, and model_construct close to a dataclass because it skips validation. Measure your own model: two fields and forty fields with constrained strings differ by an order of magnitude.

Key Comparison Table

PropertyTypedDictdataclassPydantic v2 BaseModel
Runtime type checkingNoneNoneFull, compiled
Coercion ("7" → 7)N/ANoYes, unless strict=True
JSON SchemaNoNoYes, model_json_schema()
Serialisation helperNoasdict() (deep copy)model_dump(), model_dump_json()
Unknown key handlingIgnoredTypeError on __init__extra="ignore" default, forbid option
Memory per instancedict__dict__, or compact with slots=True__dict__ + __pydantic_fields_set__
Typical construction cost1×2–3×5–10×
Error messagesNoneTypeErrorField-level, aggregated
Works in FastAPI responsesYesYesYes, preferred
TaskBest choiceWhy
HTTP request bodyPydanticUntrusted input, needs 422 errors
Third-party API responsePydantic, then map to dataclassValidate once, then hot path
Internal function argumentTypedDictNo conversion, keeps dict semantics
Row from a trusted DB driverdataclass(slots=True)Already typed by the driver
Config from envPydantic BaseSettingsCoercion and error text for free
Millions of instances in memorydataclass(slots=True)Smallest per-object footprint

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. A dataclass that silently accepts the wrong type

python
@dataclass(slots=True) class Order: id: int total: float Order(id="123", total="9.99") # accepted, and every later comparison is string-based

Add the check you need instead of validating everything:

python
@dataclass(slots=True, frozen=True) class Order: id: int total: float def __post_init__(self) -> None: if not isinstance(self.id, int) or isinstance(self.id, bool): raise TypeError(f"id must be int, got {type(self.id).__name__}") object.__setattr__(self, "total", float(self.total))

object.__setattr__ is required with frozen=True; plain assignment raises FrozenInstanceError.

2. asdict() is a deep copy and shows up in profiles

dataclasses.asdict() recurses through containers and copies every value, which costs more than model_dump() for wide records and much more than building the dict directly. For serialisation in a hot loop, write the mapping explicitly or use slots=True with a to_dict method.

python
@dataclass(slots=True) class Row: id: int name: str def to_dict(self) -> dict[str, object]: return {"id": self.id, "name": self.name}

3. Pydantic models are not free to compare or hash

BaseModel.__eq__ compares field values and class identity; two models of different classes are never equal. For cache keys, model_config = ConfigDict(frozen=True) gives __hash__. Each instance also carries __pydantic_extra__ and __pydantic_fields_set__, which a slotted dataclass does not.

4. TypeAdapter is the way to validate TypedDict and lists

You cannot call .model_validate on a TypedDict, and wrapping the whole structure in a model only to unwrap it wastes allocation. TypeAdapter compiles a validator for any supported type:

python
from pydantic import TypeAdapter Users = TypeAdapter(list[UserDict]) users = Users.validate_json('[{ "id": 1, "email": "x@y.z" }]') raw = dict(users[0]) # back to a plain dict, TypedDict at type level

The adapter is also the correct tool for list[int], dict[str, User] and unions at boundaries.

5. JSON parsing: two paths with different costs

model_validate_json() parses bytes directly in the Rust core and never builds an intermediate dict; json.loads() plus model_validate() does the work twice. On a 1 MB payload the difference is measurable, and it also affects behaviour: duplicate keys, NaN, and integer precision are handled by the core parser.

python
user = User.model_validate_json(body_bytes) # one pass # vs user = User.model_validate(json.loads(body_bytes)) # two passes

When the payload is already a dict parsed elsewhere, keep model_validate; converting back to text to use the JSON path is slower.

6. TypedDict at the boundary with no runtime guard

A TypedDict narrows types for the checker but no code runs, so a missing key surfaces later as KeyError deep in the call stack. When the data crosses a process boundary, validate once with a TypeAdapter and pass the plain dict on:

python
def handle(payload: dict) -> None: event = EventAdapter.validate_python(payload) # raises ValidationError early process(event) # event is still a dict

Common Compilation/Runtime Mistakes & Version Gotchas

  • Pydantic v1 idioms in v2. parse_obj, .dict(), .json(), class Config, and validator still exist as deprecated shims or are gone; model_validate, model_dump, model_dump_json, model_config and field_validator are the current surface. orm_mode = True became from_attributes=True.
  • dataclass(eq=True) in sets. Generated __eq__ sets __hash__ = None, so the class is unhashable. Add frozen=True or unsafe_hash=True and accept identity-by-value.
  • Mutable defaults. tags: list[str] = [] is a ValueError in dataclasses and a shared-object bug elsewhere; pydantic deep-copies the default per instance, which costs a little on every construction.
  • Coercion surprises. "false" becomes False, 1 becomes "1" for str fields, and True is accepted for int unless strict=True. Pydantic's lenient mode is convenient for forms and dangerous for financial data; set strict per field for the values where it matters.
  • Benchmarking without warmup. The first model_validate call compiles and imports the compiled core; a single-shot timing overstates pydantic by more than the models themselves cost.

Related tools. Generate a schema-shaped sample payload to benchmark against with the JSON formatter, convert a validated model to CSV for row-by-row comparison with the CSV/JSON converter, and hash a normalised model_dump() to verify two paths produce identical records with the hash generator.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.