{"id":9563,"library":"bump-pydantic","title":"bump-pydantic","description":"bump-pydantic is a command-line tool designed to automatically convert Pydantic V1 codebases to Pydantic V2 syntax. It helps users migrate their models, validators, and settings from the old API to the new one, facilitating a smoother transition. The current version is 0.8.0, and it has a regular release cadence, with several minor versions released frequently to add new features and fix issues.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/pydantic/bump-pydantic","tags":["pydantic","migration","cli","code transformation","static analysis","pydantic-v2"],"install":[{"cmd":"pip install bump-pydantic","lang":"bash","label":"Install bump-pydantic"}],"dependencies":[{"reason":"Core dependency for Abstract Syntax Tree (AST) manipulation and code transformation.","package":"libcst","optional":false}],"imports":[],"quickstart":{"code":"import os\n\n# Create a dummy Pydantic V1 file for demonstration\nwith open('my_model_v1.py', 'w') as f:\n    f.write(\n        \"\"\"from typing import Optional\nfrom pydantic import BaseModel, Field, EmailStr\n\nclass User(BaseModel):\n    name: str = Field(..., min_length=1)\n    email: EmailStr\n    age: Optional[int] = Field(None, example=30)\n\"\"\"\n    )\n\n# Run bump-pydantic on the created file\n# In a real scenario, you would run this command in your terminal\n# and typically on a directory, e.g., `bump-pydantic .`\n# For this quickstart, we'll demonstrate using a single file.\nprint(\"Running bump-pydantic on my_model_v1.py...\")\nos.system(\"bump-pydantic my_model_v1.py\")\n\n# Optionally, print the modified content\nwith open('my_model_v1.py', 'r') as f:\n    print(\"\\n--- Modified my_model_v1.py ---\")\n    print(f.read())\n\n# Clean up the dummy file\nos.remove('my_model_v1.py')\n","lang":"python","description":"This quickstart demonstrates how to use `bump-pydantic` to convert a simple Pydantic V1 model to V2 syntax. It creates a temporary Python file, runs the tool on it, and then prints the modified content. In practice, you would run `bump-pydantic` directly from your terminal on your project's directory or specific files."},"warnings":[{"fix":"Before running: `git commit -am 'Pre-bump-pydantic backup'` or `bump-pydantic --diff .`","message":"By default, `bump-pydantic` modifies files in place without a backup. Always commit your changes to version control (e.g., Git) before running the tool, or use the `--diff` argument to review changes before applying them.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your code is valid Python and update `libcst` to its latest version (automatically handled by `bump-pydantic`'s dependencies). Simplify complex expressions if persistent issues occur.","message":"The tool uses `libcst` for Abstract Syntax Tree (AST) transformation. While powerful, it may encounter `ParserSyntaxError` if your code contains advanced or non-standard Python syntax not fully supported by `libcst` (e.g., very new Python features or malformed code).","severity":"gotcha","affected_versions":"All versions"},{"fix":"After running, carefully review the diff or modified files. Consult the official Pydantic V2 migration guide for any edge cases or complex scenarios.","message":"While `bump-pydantic` automates many conversions, Pydantic V2 introduces fundamental changes that cannot always be perfectly translated automatically (e.g., `model_validator`, `field_validator` semantics, or behavior of `Optional` fields with `Field` defaults). Always manually review the generated code for correctness and Pydantic V2 best practices.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update `bump-pydantic` to version 0.7.0 or newer. Manually convert `example='value'` to `examples=['value']` if using older versions or if the tool misses a conversion.","message":"In version 0.7.0, the `example` argument in `Field` was converted to `examples` (a list), aligning with OpenAPI specification changes in Pydantic V2. Previous versions might not handle this, or only handle `example` as a single value.","severity":"gotcha","affected_versions":"Prior to 0.7.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"First, ensure your Python code is syntactically correct and can be run by the interpreter. If the code is valid, try updating `bump-pydantic` (which often brings updated `libcst` versions). If the issue persists, isolate the problematic code snippet and simplify it if possible, or report the issue to the `libcst` or `bump-pydantic` maintainers.","cause":"The `bump-pydantic` tool relies on `libcst` to parse your Python code. This error occurs if `libcst` cannot parse a file due to invalid Python syntax, an unsupported syntax feature (e.g., very new Python versions or complex annotations), or a bug in `libcst` itself.","error":"cst.ParserSyntaxError: Syntax error while parsing the provided code."},{"fix":"Double-check that you are running `bump-pydantic` on the correct directory or files that contain Pydantic V1 code. Verify that the files are not excluded by any `.bump-pydantic-ignore` or command-line ignore patterns. If you expect changes, manually review your code to confirm it indeed uses Pydantic V1 syntax.","cause":"This message (improved in 0.8.0) indicates that the tool ran but found no Pydantic V1 constructs to convert in the specified paths, or that your files were already in Pydantic V2 format, or that files were excluded by `--ignore` patterns.","error":"No files were modified by bump-pydantic."},{"fix":"Ensure you have installed the package correctly using `pip install bump-pydantic`. If using a virtual environment, activate it before running the command. If installed, you might need to specify the full path to the executable or ensure your PATH environment variable is set correctly.","cause":"The `bump-pydantic` executable is not in your system's PATH, typically because the package was not installed or installed into an environment not currently active.","error":"bump-pydantic: command not found"}]}