Pydantic Partial Models

0.10.2 · active · verified Fri Apr 17

pydantic-partial is a Python library that allows you to create 'partial' Pydantic models. These partial models can have some or all of their fields marked as optional (allowing `None` values) or removed from being required, making them suitable for PATCH requests or incremental updates where not all data is available. The current version is 0.10.2, and it maintains an active release cadence with minor updates and dependency bumps every few weeks or months.

Common errors

```
ValidationError: field required (type=value_error.missing)
```
cause Attempting to instantiate a partial model without providing a value (or `None`) for a field that was marked as optional, but not explicitly excluded as 'required' by the partialization logic.

fix Ensure you understand the difference between `create_partial_model(Model)` (makes fields `Optional[T]`) and `create_partial_model(Model, exclude_required_fields=True)` (makes fields completely omittable). If you intended for the field to be omittable, use `exclude_required_fields=True`.
```
PydanticUserError: Pydantic V1 models are no longer supported, upgrade to Pydantic V2
```
cause You are trying to use `pydantic-partial` version 0.8.0 or newer with a project that still uses Pydantic V1.

fix Upgrade Pydantic to V2 (`pip install pydantic==2.*`) or downgrade `pydantic-partial` to a version `<0.8.0` if you need to maintain Pydantic V1 compatibility.
```
ImportError: cannot import name 'Partial' from 'pydantic_partial'
```
cause This error is unlikely with recent versions as `Partial` is exported. However, if seen, it might be due to an older `pydantic-partial` version or confusion between `pydantic.Partial` and `pydantic_partial.Partial`.

fix Ensure you have `pydantic-partial` installed and are using a version that exports `Partial` at the top level. Most commonly, `create_partial_model` is the function to use, which is always available from `pydantic_partial`.

Warnings

breaking pydantic-partial v0.8.0 and higher dropped support for Pydantic v1. If you are using Pydantic v1, you must either upgrade to Pydantic v2 or keep pydantic-partial at a version less than 0.8.0.
Fix: Upgrade Pydantic to version 2.x (`pip install pydantic==2.*`) or pin `pydantic-partial<0.8.0`.
gotcha Pydantic v2 introduced its own `Partial` type (e.g., `from pydantic import Partial`). This is distinct from `pydantic-partial`'s `Partial` type and `create_partial_model` functionality. Be careful to import the correct `Partial` or use `create_partial_model` from `pydantic_partial` to ensure the expected behavior.
Fix: For `pydantic-partial`'s full recursive optionality, use `from pydantic_partial import create_partial_model` or `from pydantic_partial import Partial`. If you intend to use Pydantic v2's built-in `Partial` (which has different behavior), import it from `pydantic`.
breaking Python 3.9 and older are no longer supported. pydantic-partial now requires Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or newer. For older Python versions, you must use an older `pydantic-partial` release (e.g., `<0.6.0`).
gotcha When dealing with nested Pydantic models, `create_partial_model` by default only makes the top-level fields optional. To make fields within nested models also optional, you must pass `recursive=True`.
Fix: Use `PartialNestedModel = create_partial_model(BaseModelWithNested, recursive=True)`.

Install

pip install pydantic-partial Install stable version

Imports

create_partial_model
wrong:
```
from pydantic_partial.partial import create_partial_model
```
correct:
```
from pydantic_partial import create_partial_model
```
The function is exposed directly at the top-level package, avoid importing from internal modules.
Partial
wrong:
```
from pydantic import Partial
```
correct:
```
from pydantic_partial import Partial
```
Pydantic v2 also has a `Partial` type (`pydantic.main.Partial`) which works differently. Ensure you import the correct `Partial` if you intend to use `pydantic-partial`'s specific implementation that makes all fields optional recursively.

Quickstart

This quickstart demonstrates how to create a basic Pydantic model and then use `create_partial_model` to generate a new model where all original fields become optional. It also shows how to use `exclude_required_fields=True` to make fields not just optional (allowing `None`) but also completely omittable from input, ideal for PATCH operations.

from pydantic import BaseModel
from pydantic_partial import create_partial_model

class User(BaseModel):
    name: str
    email: str
    age: int = 18
    is_active: bool = True

# Create a partial model where all fields are optional
PartialUser = create_partial_model(User)

# Instantiate the partial model with only some fields
partial_user_data = {
    "name": "Alice",
    "age": None # age is optional now
}
user_update = PartialUser(**partial_user_data)

print(user_update.model_dump())

# Create a partial model excluding required fields, making them Optional
# and allowing fields to be completely omitted from input
PartialUserPatch = create_partial_model(User, exclude_required_fields=True)

patch_data = {
    "email": "alice@example.com"
} # name is not required now
patch_user = PartialUserPatch(**patch_data)

print(patch_user.model_dump())

view raw JSON →