TypedDict vs Pydantic

Introduction

When you're working with structured data in Python, there are two common options: TypedDict (from the typing module) and Pydantic (a popular validation library). Both are useful, but they serve different needs depending on whether you prioritize static type checking, runtime validation, or performance.

In this post, we’ll compare them head‑to‑head and give you practical insight into when to use each.

Feature Comparison

TypedDict: Lightweight Type Hints

Use TypedDict when your main goal is to benefit from type hints during development. It’s fast, minimal, and ideal if you don't need runtime guarantees.

from typing import TypedDict

class VLAN(TypedDict):
    id: int
    name: str

vlan10: VLAN = {"id": 10, "name": "Management"} # Checked by tools like mypy

Remember: TypedDict only helps during development, it won’t protect you from invalid data at runtime.

# Wrong type at runtime (no error until you run into issues later)
vlan_bad: VLAN = {"id": "not-an-int", "name": "Data"}
print(vlan_bad)  # Allowed at runtime, but incorrect
# Output:
# {'id': 'not-an-int', 'name': 'Data'}

Pydantic: Runtime Safety & Defaults

If you need safe runtime behavior, use Pydantic. It not only validates input, but also converts compatible types, making it a robust choice for external data (e.g. API inputs).

Here you can see that Pydantic converts the str to int at runtime.

from pydantic import BaseModel

class VLAN(BaseModel):
    id: int
    name: str

# Built-in type conversion: "20" → 20
vlan20 = VLAN(id="20", name="Data")
print(vlan20)  
# Output:
# id=20 name='Data'

If the conversion isn’t possible, Pydantic raises a clear validation error instead:

from pydantic import ValidationError

try:
    vlan30 = VLAN(id="not-an-int", name="Data")
except ValidationError as e:
    print(e)
# Output:
# 1 validation error for VLAN
# id
#   Input should be a valid integer [type=int_parsing, input_value='not-an-int', input_type=str]

When to Choose What

• TypedDict

  • Use it for static type hints
  • Super lightweight and fast
  • Best when runtime validation isn't needed

• Pydantic

  • Use it when you need runtime validation, default handling, and type conversion
  • Slight runtime cost, but significantly safer for handling real-world input

Summary

TypedDict is perfect for development-time type checks.
Pydantic is the choice for safe, validated, and flexible data handling at runtime.

That’s all from us!

Thanks for reading and happy coding!

---
Team Packet Coders