Issues¶

Questions, feature requests and bug reports are all welcome asdiscussions or issues.However, to report a security vulnerability, please see oursecurity policy.

To make it as simple as possible for us to help you, please include the output of the following call in your issue:

python-c"import pydantic.version; print(pydantic.version.version_info())"

python-c"import pydantic.utils; print(pydantic.utils.version_info())"

Please try to always include the above unless you're unable to install Pydantic orknow it's not relevantto your question or feature request.

Pull Requests¶

It should be extremely simple to get started and create a Pull Request.Pydantic is released regularly so you should see your improvements release in a matter of days or weeks 🚀.

Unless your change is trivial (typo, docs tweak etc.), please create an issue to discuss the change beforecreating a pull request.

If you're looking for something to get your teeth into, check out the"help wanted"label on github.

To make contributing as easy and fast as possible, you'll want to run tests and linting locally. Luckily,Pydantic has few dependencies, doesn't require compiling and tests don't need access to databases, etc.Because of this, setting up and running the tests should be very simple.

Prerequisites¶

You'll need the following prerequisites:

• Any Python version betweenPython 3.9 and 3.12
• uv or other virtual environment tool
• git
• make

Installation and setup¶

Fork the repository on GitHub and clone your fork locally.

# Clone your fork and cd into the repo directorygitclone[email protected]:<yourusername>/pydantic.gitcdpydantic# Install UV and pre-commit# We use pipx here, for other options see:# https://docs.astral.sh/uv/getting-started/installation/# https://pre-commit.com/#install# To get pipx itself:# https://pypa.github.io/pipx/pipxinstalluvpipxinstallpre-commit# Install pydantic, dependencies, test dependencies and doc dependenciesmakeinstall

Check out a new branch and make your changes¶

Create a new branch for your changes.

# Checkout a new branch and make your changesgitcheckout-bmy-new-feature-branch# Make your changes...

Run tests and linting¶

Run tests and linting locally to make sure everything is working as expected.

# Run automated code formatting and lintingmakeformat# Pydantic uses ruff, an awesome Python linter written in rust# https://github.com/astral-sh/ruff# Run tests and lintingmake# There are a few sub-commands in Makefile like `test`, `testcov` and `lint`# which you might want to use, but generally just `make` should be all you need.# You can run `make help` to see more options.

Build documentation¶

If you've made any changes to the documentation (including changes to function signatures, class definitions, or docstrings that will appear in the API documentation), make sure it builds successfully.

We usemkdocs-material[imaging] to support social previews.You can find directions on how to install the required dependencieshere.

# Build documentationmakedocs# If you have changed the documentation, make sure it builds successfully.# You can also use `uv run mkdocs serve` to serve the documentation at localhost:8000

If this isn't working due to issues with the imaging plugin, try commenting out thesocial plugin line inmkdocs.yml and runningmake docs again.

Updating the documentation¶

We push a new version of the documentation with each minor release, and we push to adev path with each commit tomain.

If you're updating the documentation out of cycle with a minor release and want your changes to be reflected onlatest,do the following:

1. Open a PR againstmain with your docs changes
2. Once the PR is merged, checkout thedocs-update branch. This branch should be up to date with the latest patch release.For example, if the latest release isv2.9.2, you should make suredocs-update is up to date with thev2.9.2 tag.
3. Checkout a new branch fromdocs-update and cherry-pick your changes onto this branch.
4. Push your changes and open a PR againstdocs-update.
5. Once the PR is merged, the new docs will be built and deployed.

Commit and push your changes¶

Commit your changes, push your branch to GitHub, and create a pull request.

Please follow the pull request template and fill in as much information as possible. Link to any relevant issues and include a description of your changes.

When your pull request is ready for review, add a comment with the message "please review" and we'll take a look as soon as we can.

Documentation style¶

Documentation is written in Markdown and built usingMaterial for MkDocs. API documentation is build from docstrings usingmkdocstrings.

Code documentation¶

When contributing to Pydantic, please make sure that all code is well documented. The following should be documented using properly formatted docstrings:

• Modules
• Class definitions
• Function definitions
• Module-level variables

Pydantic usesGoogle-style docstrings formatted according toPEP 257 guidelines. (SeeExample Google Style Python Docstrings for further examples.)

pydocstyle is used for linting docstrings. You can runmake format to check your docstrings.

Where this is a conflict between Google-style docstrings and pydocstyle linting, follow the pydocstyle linting hints.

Class attributes and function arguments should be documented in the format "name: description." When applicable, a return type should be documented with just a description. Types are inferred from the signature.

classFoo:"""A class docstring.    Attributes:        bar: A description of bar. Defaults to "bar".    """bar:str='bar'

defbar(self,baz:int)->str:"""A function docstring.    Args:        baz: A description of `baz`.    Returns:        A description of the return value.    """return'bar'

You may include example code in docstrings. This code should be complete, self-contained, and runnable. Docstring examples are tested, so make sure they are correct and complete. SeeFieldInfo.from_annotated_attribute for an example.

Documentation Style¶

In general, documentation should be written in a friendly, approachable style. It should be easy to read and understand, and should be as concise as possible while still being complete.

Code examples are encouraged, but should be kept short and simple. However, every code example should be complete, self-contained, and runnable. (If you're not sure how to do this, ask for help!) We prefer print output to naked asserts, but if you're testing something that doesn't have a useful print output, asserts are fine.

Pydantic's unit test will test all code examples in the documentation, so it's important that they are correct and complete. When adding a new code example, use the following to test examples and update their formatting and output:

# Run tests and update code examplespytesttests/test_docs.py--update-examples

Debugging Python and Rust¶

If you're working withpydantic andpydantic-core, you might find it helpful to debug Python and Rust code together.Here's a quick guide on how to do that. This tutorial is done in VSCode, but you can use similar steps in other IDEs.

Badges¶

Pydantic has a badge that you can use to show that your project uses Pydantic. You can use this badge in yourREADME.md:

With Markdown¶

[![Pydantic v1](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json)](https://pydantic.dev)[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)

With reStructuredText¶

..image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json:target: https://pydantic.dev:alt: Pydantic..image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json:target: https://pydantic.dev:alt: Pydantic

With HTML¶

<ahref="https://pydantic.dev"><imgsrc="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json"alt="Pydantic Version 1"style="max-width:100%;"></a><ahref="https://pydantic.dev"><imgsrc="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json"alt="Pydantic Version 2"style="max-width:100%;"></a>

Adding your library as part of Pydantic's third party test suite¶

To be able to identify regressions early during development, Pydantic runs tests on various third-party projectsusing Pydantic. We consider adding support for testing new open source projects (that rely heavily on Pydantic) if your said project matches some of the following criteria:

• The project is actively maintained.
• The project makes use of Pydantic internals (e.g. relying on theBaseModel metaclass, typing utilities).
• The project is popular enough (although small projects can still be included depending on how Pydantic is being used).
• The project CI is simple enough to be ported into Pydantic's testing workflow.

If your project meets some of these criteria, you canopen feature requestto discuss the inclusion of your project.