Guide · Open source

How to use Pydantic: define models and validate data in Python

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Pydantic is a Python library that checks data against the shape you describe using ordinary type hints on classes. You define a model, pass in raw data such as a dictionary parsed from JSON, and Pydantic converts values to the right types or raises an error if they do not fit. This guide shows how to install it, write a model, and understand what it does with incoming data.

Pydanticpydantic/pydantic · ★ 29.3k · MIT Install options & downloads

Quick start

1Check your Python version. Confirm you have Python 3.10 or newer, since the README lists this as the minimum.
2Install the package. Run pip install -U pydantic, or use conda install pydantic -c conda-forge.
3Import BaseModel. Import BaseModel from the pydantic package in your Python file.
4Define a model class. Create a class that inherits from BaseModel and declare each field with a type hint.
5Pass in data. Create an instance by passing a dictionary, such as one loaded from JSON, using ** unpacking.
6Read the typed fields. Access the validated values as attributes, such as user.id, which is an integer.

Install Pydantic with pip or conda

Pydantic requires Python 3.10 or newer. You can install it with pip, the standard Python package manager, or with conda from the conda-forge channel.

pip: use the upgrade flag to get the latest release
conda: install from the conda-forge channel

pip install -U pydantic
conda install pydantic -c conda-forge

Define a model with BaseModel

A model is a Python class that inherits from BaseModel. Each field is declared with a type hint, and a field can have a default value. Pydantic uses these hints to decide how to validate and convert the data you pass in.

Fields with a type hint and no default are required
Fields with a default value, such as name: str = 'John Doe', are optional
Optional[datetime] = None allows the value to be missing or None

from datetime import datetime
from typing import Optional
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str = 'John Doe'
    signup_ts: Optional[datetime] = None
    friends: list[int] = []

Create a model instance from raw data

Pass a dictionary to the model, unpacked with **, to create an instance. Pydantic converts values where it can. In the README example, the string '123' becomes the integer 123, the string '2017-06-01 12:22' becomes a datetime, and the mixed list [1, '2', b'3'] becomes a list of integers.

external_data = {'id': '123', 'signup_ts': '2017-06-01 12:22', 'friends': [1, '2', b'3']}
user = User(**external_data)
print(user)
print(user.id)

Understand conversion and errors

Pydantic either converts a value into the declared type or rejects it. The README describes it as raising an error when values do not fit the shape you described. This is what makes it useful for checking input before your program relies on it. The README does not list every error format, so check the documentation for the full error details.

When you need data from a JSON or config file, load it into a dictionary first and pass that dictionary to your model.

Upgrade from Pydantic V1 gradually

Pydantic V2 is a ground-up rewrite with new features, performance improvements and some breaking changes compared with V1. The README notes that V2 includes the latest V1.10 code under pydantic.v1, so you can migrate a project step by step.

If you still rely on V1, the README points to the V1.10 documentation and a 1.10.X-fixes git branch.

from pydantic import v1 as pydantic_v1

Find more detail in the official docs

The README links to the full documentation for getting started, installation options and contributing. Use it for features beyond the simple example in this guide.

What people use it for

Checking the shape of JSON data before a program uses it
Turning config file values into typed Python objects
Returning clear validation errors for user or API input
Upgrading an existing V1 codebase one part at a time

Frequently asked questions

Is Pydantic free to use?

Pydantic is released under the MIT licence, according to the project's repository details. Check the LICENSE file in the repository for the full terms.

What are the requirements for Pydantic?

Pydantic needs Python 3.10 or newer, according to the README. You install it with pip or conda.

How do I install Pydantic?

Run pip install -U pydantic, or run conda install pydantic -c conda-forge. The README also links to the documentation's install page for more options.

Can Pydantic convert the string '123' to an integer?

Yes. The README example shows the string '123' being converted to the integer 123 for a field declared as int.

What are alternatives to Pydantic?

The project lists marshmallow, attrs, dataclasses-json and cattrs as comparable projects. This guide does not compare them in detail, so check each project's documentation.

Can I use Pydantic with code that is not written in Python?

No. The library is Python-only, and models are written as Python classes.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Pydantic suits Python developers who already use type hints and want runtime checks on incoming data, especially for JSON, config files or API input. It is not a good choice if you do not write Python or need a no-code tool, and it will not run on Python versions older than 3.10.

Install options & downloads