python pydantic v1 vs v2: Key Differences and Migration
Compare python pydantic v1 vs v2: API changes, validation behavior, performance, and a practical migration path for existing projects.

Choosing between Pydantic v1 and v2 for a Python project depends on the API changes, validation behavior, and migration effort that matter for your code. Pydantic v2 is the recommended version for new projects, but an existing v1 codebase needs a deliberate migration.
When migrating from Pydantic v1 to v2, the most immediate change is the API surface for parsing and serialization. Methods like parse_obj and dict are replaced by model_validate and model_dump. This is not a cosmetic rename; the new methods align with the v2 core architecture and enforce stricter validation semantics. Understanding these differences is critical for a smooth upgrade.
What Changed in the Core API
The v2 API renames several commonly used methods and changes how configuration is declared. The table below shows the most frequent replacements:
| v1 Method / Attribute | v2 Replacement | Notes |
|---|---|---|
parse_obj | model_validate | Accepts a dict or object; raises ValidationError on failure |
parse_raw | model_validate_json | Parses JSON directly |
dict | model_dump | Returns a dict; use model_dump_json for JSON string |
json | model_dump_json | Serializes to JSON string |
schema | model_json_schema | Generates JSON Schema |
Config class | model_config dict | Use ConfigDict for type hints |
@validator | @field_validator | New decorator with different signature |
@root_validator | @model_validator | Now supports mode before/after |
orm_mode | from_attributes | Set in model_config |
For example, in v1 you might write:
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
user = User.parse_obj({'name': 'Alice', 'age': 30})
data = user.dict()In v2, the equivalent is:
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
user = User.model_validate({'name': 'Alice', 'age': 30})
data = user.model_dump()The old methods still exist in v2 but are deprecated and may raise warnings. They will be removed in a future release, so updating calls is a necessary part of migration.
Validation and Type Handling Differences
Pydantic v2 introduces a more consistent validation engine, but it also changes some default behaviors. String-to-numeric coercion still happens in lax mode, as it did in v1, but the rules are more predictable and some edge cases are stricter.
One notable difference is how bool values are treated for int fields. In v1, because Python treats bool as a subclass of int, a value like True was often accepted by an int field. Pydantic v2 does not use that implicit relationship by default, so True will fail validation for an int field unless the model includes an explicit validator. The coerce_numbers_to_str config option is unrelated to this behavior; it affects numeric-to-string coercion, not bool-to-int coercion.
The @field_validator decorator also changes how custom validators are declared. In v2, the common form is a classmethod that receives cls and the value to validate:
from pydantic import BaseModel, field_validator
class Product(BaseModel):
name: str
price: float
@field_validator('price')
@classmethod
def check_positive(cls, v):
if v <= 0:
raise ValueError('price must be positive')
return vIn v1, you used @validator('price') and Pydantic automatically treated the function as a classmethod. In v2, the decorator form is different, and many existing models need to be updated to the new signature.
Performance and Runtime Behavior
Pydantic v2's core validation is implemented in Rust, which gives it a significant speed advantage over the pure-Python v1 engine. The performance gain comes from reducing the overhead of Python function calls during validation and using optimized data structures. While exact numbers depend on your schema complexity, the underlying mechanism is that v2 compiles validators into a fast execution path.
This improvement matters in high-throughput scenarios such as parsing API requests, validating configuration files, or processing large batches of data. In v1, each field validation involved multiple Python-level checks; v2 reduces that to a more direct path. The memory footprint is also lower because v2 avoids creating intermediate Python objects when possible.
If you are running a service that validates thousands of objects per second, upgrading to v2 can reduce CPU usage and latency. However, you should not rely on micro-benchmarks; instead, profile your own workload after migration to confirm the benefit.
Migration Path from v1 to v2
A practical migration starts with upgrading the package and running your test suite. Pydantic v2 provides the pydantic.v1 namespace for legacy code, but that is not a long-term solution.
For most projects, you can automate the mechanical changes with a script that replaces method names and decorators. For example, replace parse_obj with model_validate, dict with model_dump, and @validator with @field_validator. Then adjust the Config class to model_config = ConfigDict(...).
Here is a before-and-after example for a model with custom config:
# v1
from pydantic import BaseModel, validator
class Settings(BaseModel):
debug: bool = False
class Config:
orm_mode = True
@validator('debug')
def check_debug(cls, v):
return v# v2
from pydantic import BaseModel, ConfigDict, field_validator
class Settings(BaseModel):
model_config = ConfigDict(from_attributes=True)
debug: bool = False
@field_validator('debug')
@classmethod
def check_debug(cls, v):
return vAfter updating the code, run your tests and address any validation errors that surface. The error messages in v2 are more detailed, which helps pinpoint where the old behavior was too permissive.
Handling Edge Cases and Compatibility
Some v1 features require manual review rather than a simple rename. For example, a @root_validator(skip_on_failure=True) needs to be rewritten as @model_validator(mode='before') or mode='after' depending on whether the logic should run before or after the rest of validation. In after mode, the validator only runs when earlier validation succeeds, which matches the usual skip_on_failure intent. The allow_population_by_field_name config is now populate_by_name. These changes require manual review.
Another common issue is the handling of Union types. In v1, the order of types in a Union mattered because validation tried each type in order. In v2, the validator uses a smart mode that may choose a different type based on the input. This can lead to different results for ambiguous inputs. For instance, a field typed as Union[int, str] will now parse '123' as a string instead of an integer, because the string type is a more precise match. In v1, it would have tried int first and converted it.
If you rely on the old behavior, you can use Field(union_mode='left_to_right') to preserve v1 semantics. This is a key compatibility consideration for existing code.
Choosing v1 or v2 for a New Project
For any new Python project, v2 is the clear choice. It is actively maintained, faster, and has a cleaner API. The v1 branch is in maintenance mode and will not receive new features. If you are starting fresh, you should use v2 from the beginning and design your models with the new API in mind.
If you have a large existing codebase, the decision is more nuanced. You can run v1 and v2 side-by-side by importing pydantic.v1 for legacy modules, but this adds dependency complexity. A better strategy is to migrate incrementally: update models one by one, using the compatibility layer to catch issues, and then remove the v1 import once all models are converted.
One practical tip is to use the model_config dict for all configuration and to enable strict mode selectively where you need it. This reduces surprises and makes the validation behavior explicit. The migration effort is usually proportional to the number of custom validators and config options you have. For simple models, the change is mostly mechanical; for complex ones, you need to test edge cases carefully.
Pydantic v2 also introduces new features like TypeAdapter for validating non-model types, and ValidationInfo for accessing context in validators. These are worth exploring after migration, as they can simplify code that previously required workarounds in v1.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.