As the lead of a large Pydantic 1 codebase, how would you plan its move to Pydantic 2, and what would you refuse to do in a single step?
answer
- separate the upgrade from the change
- imports first, behaviour later
- migrate clusters, not files
- decide which old rules to keep
- warnings become the finish line
basics
~20 sStage it: switch imports to pydantic.v1 while still on version 1, upgrade the package with no behaviour change, then migrate clusters of linked models one at a time with bump-pydantic and payload-diff tests. Never upgrade and change behaviour in one step.
solid answer
~50 sI would separate three things that a big-bang migration mixes: the dependency upgrade, the API rewrite and the behaviour change. First, on `pydantic>=1.10.17`, point every import at `pydantic.v1`, then upgrade to Pydantic 2; nothing behaves differently yet. Second, map which models nest which, because version 1 and version 2 models cannot be mixed, and migrate one cluster per change, using `bump-pydantic` for the mechanical rewrite and reviewing validators and config by hand. Third, for each inbound contract, decide whether to accept Pydantic 2's stricter conversion or pin the old rule explicitly (`coerce_numbers_to_str`, `union_mode='left_to_right'`, a `None` default), backed by a test that diffs old and new output on recorded payloads. I would refuse to rename, upgrade and accept new behaviour in one pull request, because then no reviewer can tell a rename from a contract change. Done means nothing imports `pydantic.v1` and Pydantic deprecation warnings fail CI.
go deeper
Recall that a Pydantic 2 migration can run in stages through the pydantic.v1 namespace instead of one big change.
Explain the stages: switch imports to pydantic.v1, upgrade the package, then migrate models with bump-pydantic and hand review.
Show the risks you would test for: mixed clusters, behaviour changes invisible to rename tools, and leftover deprecations hidden by Python's warning filters.
Own the contract decision: per inbound model, accept Pydantic 2's stricter rules and tell clients, or pin the old rule with an owner, a reason and a review date.
## The constraints that shape the plan Four facts from Pydantic's own documentation decide most of the plan: - **Version 1 and version 2 models cannot be mixed.** A Pydantic 2 model that references a `pydantic.v1` model gets a warning that this is unsupported, so linked models move together. - **Old names keep working, with a deadline.** Deprecated version 1 methods and decorators still run on every 2.x release, emit `PydanticDeprecatedSince20`, and go away in version 3. - **The version 1 line gets critical and security fixes only, until version 3 is released.** `pydantic.v1` is a bridge with an end date. - **Some changes are invisible in source.** Required `Optional` fields, no number-to-string coercion, no fractional float-to-int truncation, smart unions and narrower subclass dumps all happen with no code change, so no rename tool can find them. ## A staged route 1. **Pin the bridge.** On version 1, require `pydantic>=1.10.17` and rewrite imports to `pydantic.v1`. Ship it; behaviour cannot change. 2. **Upgrade the package** to Pydantic 2. Everything still runs version 1 semantics through the namespace, and other dependencies that need Pydantic 2 are unblocked. 3. **Map clusters.** List which models nest or reference which, and group them; order clusters from the leaves of the graph or from the lowest-risk internal models. 4. **Migrate one cluster per change.** Run `bump-pydantic` (a beta code-transformation tool from the Pydantic team) for the mechanical part, then review validators, config keys and root models by hand. 5. **Diff behaviour.** For each cluster, run recorded payloads through the old `pydantic.v1` definition and the new model, and resolve every difference deliberately. 6. **Close the door.** Once a cluster is done, make Pydantic deprecation and config warnings fatal for its tests so nothing slides back. ## Deciding how much version 1 behaviour to keep This is the judgment call. Accepting Pydantic 2's rules is cleaner, but for an inbound contract it is a change clients feel. | Change | Keep version 1 behaviour with | Usually keep it when | |---|---|---| | numbers into `str` fields | `ConfigDict(coerce_numbers_to_str=True)` | partners already send numeric IDs | | `int \| str` turning `'7'` into 7 | `Field(union_mode='left_to_right')` | downstream code relies on the int | | `Optional` field optional | an explicit `= None` default | the field was genuinely optional | | regex with lookarounds | `ConfigDict(regex_engine='python-re')` | rewriting the pattern is risky | | fractional floats into `int` | a before-mode validator that truncates | almost never; it hid data loss | Each pinned rule should be scoped to the models that need it, written down, and given an owner who decides later whether clients can be moved. ## What I would refuse to do in one step - **Upgrade, rename and change behaviour in one pull request.** Reviewers cannot tell a mechanical rename from a contract change, and a rollback undoes all three. - **Migrate by file instead of by cluster.** Half a cluster on each side of the boundary is the unsupported mixed state. - **Trust a green test suite as proof.** Fixtures with canonical data pass on both versions; only real payloads show the conversion changes. - **Leave deprecated names as the end state.** They are removals scheduled for version 3, and their warnings drown out new ones. ## Keeping the bridge from growing - **Freeze new version 1 code.** Once the package is upgraded, code review or a lint rule rejects new imports from `pydantic.v1`; new models start on the Pydantic 2 API. - **Give each cluster an owner** and a target release, so the migration is tracked work rather than a background chore. - **Watch the clock.** The version 1 line gets fixes only until version 3, and Python upgrades have already outpaced it once, so a long tail on `pydantic.v1` is a standing risk, not a neutral state. ## How to measure done - No module imports from `pydantic.v1`. - No class defines `class Config`, `@validator` or `@root_validator`. - `PydanticDeprecatedSince20` and the config-key `UserWarning` are errors in CI. - Every pinned version 1 rule has an owner and a recorded reason. - The payload-diff tests are deleted together with the last version 1 definitions they compared.
- How would you order the clusters?Start where risk is low and reach is small: internal models no client sends to, then outbound models, then inbound contracts with partners, which need the most behaviour decisions. Within that, prefer clusters other teams wait on, since migrating them unblocks other work. A cluster that nests a widely shared model waits until that shared model's cluster can move with it.
- When would you not stage the migration?When the codebase is small enough that every model fits in one reviewable change, has no external clients whose payloads could break, and has good payload-level tests. Then the bridge costs more than it saves, and a single branch with the rename tool plus a hand review is simpler.
- Run bump-pydantic across the repository, merge, and the migration is done
- Migrate file by file, leaving nested models on whichever version they are on
- Keep the deprecated version 1 names forever because they still work
- Turn on strict mode everywhere during the migration to be safe
- A green test suite proves that no payload behaviour changed
Assumes a move from Pydantic 1.10 to Pydantic 2 (checked on 2.14.0); the pydantic.v1 bridge needs 1.10.17 or later, and deprecated names last until version 3.