How to Use the Pydantic v1 to v2 Migration Prompt to Upgrade Models Without Silent Behavior Changes

Pydantic v2 is faster and stricter, and many libraries now expect it, but the upgrade is not only a rename. Validators change shape, Config becomes model_config with renamed keys, BaseSettings moves to a separate package, and a few behaviors change quietly. An Optional field with no default becomes required, and an integer is no longer turned into a string for you. The Pydantic v1 to v2 Migration Planner for FastAPI and Python Services: bump-pydantic First Pass, validator to field_validator, root_validator to model_validator, Config to ConfigDict, BaseSettings Move, and Behavior Changes prompt plans the migration the way an experienced backend engineer would: bump-pydantic for the mechanical pass, hand edits for what it cannot fix, and tests aimed at the behaviors that change.

What the prompt produces

1. A plan header with dependency changes, including pydantic-settings when BaseSettings is used, and whether a gradual path through the pydantic.v1 namespace makes sense.
2. A bump-pydantic first pass with the command to run and a list of what it will and will not rewrite.
3. Validator conversions from @validator to @field_validator and from @root_validator to @model_validator, with the right mode.
4. Config conversions to ConfigDict with renamed keys such as orm_mode to from_attributes.
5. Field changes such as regex to pattern, custom root models to RootModel, and Optional fields that need an explicit default.
6. Call site replacements such as dict to model_dump and parse_raw to model_validate_json.
7. Behavior change tests written as pytest cases.
8. A rollout checklist with what to watch after deploy.

How to fill the inputs

Versions lists Python, the current pydantic and framework versions, and the targets.

ModelCode is the pasted models, validators, Config classes, and settings classes. The prompt shows before and after code for each one.

CallSites describes where the code calls dict, json, parse_obj, parse_raw, from_orm, schema, copy, or the fields attribute.

TestNotes covers existing tests and known production payloads, such as producers that send numbers as strings.

Rollout says whether you can migrate in one pass or need to move gradually across services.

Reading the example output

The example migrates an Order model and a Settings class in a single FastAPI service:

• The plan skips the shim. One repo and one service means a single pass without the pydantic.v1 namespace.
• The Optional trap is caught. The note field gets an explicit default of None, with a comment explaining that v2 would otherwise make it required.
• The root validator becomes an after model validator. It now reads attributes on the built model instead of a values dictionary.
• Config moves cleanly: orm_mode becomes from_attributes, and Settings uses SettingsConfigDict with the same env prefix.
• Call sites are mapped one to one, including from_orm becoming model_validate, which works because from_attributes is set.
• Four tests target real risks: a string id that should still parse, the optional note, the bulk order rule, and the dumped output shape.

Tips for better results

• Paste real model code, not a summary. Validator bodies are where the hand edits happen.
• List known odd payloads in TestNotes. They become test cases that protect you after deploy.
• Run bump-pydantic on a clean branch so its diff is easy to review on its own.
• Search for leftover v1 calls after the edits. A quick grep for .dict( and parse_obj catches most stragglers.

Mistakes to avoid

• Do not assume Optional still means not required. Give every optional field an explicit default.
• Do not keep reading values inside an after model validator. Use the model's attributes.
• Do not forget pydantic-settings when the code uses BaseSettings.
• Do not ship without tests for coercion. Inputs that v1 accepted quietly may now fail validation.

Who it is for

Python backend developers on FastAPI or worker services, maintainers of libraries that expose Pydantic models, and teams with a dependency upgrade deadline who want a careful plan rather than a search and replace.

Related PromptDig links

Open the Pydantic v1 to v2 Migration Planner for FastAPI and Python Services: bump-pydantic First Pass, validator to field_validator, root_validator to model_validator, Config to ConfigDict, BaseSettings Move, and Behavior Changes prompt and paste your models. For more coding prompts, Browse more prompts. If you have a migration or refactoring prompt that works well, Share a prompt.