datamodel-code-generator
🚀 Generate Python data models from schema definitions in seconds.
📚 Documentation · 🧪 Playground · 💼 Lead maintainer available for work
[!NOTE] Playground privacy: Generation runs locally in your browser with Pyodide. Your schema and options are not sent to a backend. Shared repro URLs encode them in the URL fragment (
#state=...), which browsers do not send to the server; the full URL can still be stored in your browser history or wherever you share it.
✨ What it does
Pick any one of the supported inputs and pick the Python model style you want as output.
--input-model path/to/file.py:ClassName can even retarget an existing Pydantic, dataclass, or TypedDict class defined
in another Python file to a different output type.
- 📄 Converts OpenAPI 3, AsyncAPI, JSON Schema, Apache Avro, XML Schema, Protocol Buffers/gRPC, GraphQL, MCP tool schemas, and raw data (JSON/YAML/CSV) into Python models
- 🐍 Generates from existing Python types (Pydantic, dataclass, TypedDict) via
--input-model - 🎯 Generates Pydantic v2, Pydantic v2 dataclass, dataclasses, TypedDict, or msgspec output
- 🔗 Handles complex schemas:
$ref,allOf,oneOf,anyOf, enums, and nested types - ✅ Produces type-safe, validated code ready for your IDE and type checker
📦 Installation
Recommended for standalone CLI use:
uv tool install datamodel-code-generator
Conda users can install from conda-forge:
conda install -c conda-forge datamodel-code-generator
For projects that should pin the generator version, add it as a development dependency instead:
uv add --dev datamodel-code-generator
[!NOTE] Community-maintained distribution packages are also available from Debian, Ubuntu, nixpkgs, and openSUSE Tumbleweed. Availability and versions vary by distribution.
Other installation methods
pip:
pip install datamodel-code-generator
uv (run without adding to project):
uv run --with datamodel-code-generator datamodel-codegen --help
With stable HTTP support (for resolving remote $ref):
pip install 'datamodel-code-generator[http]'
The http extra is supported and is not deprecated. To require the experimental
HTTPX2 backend instead, install datamodel-code-generator[httpx2] and pass
--http-backend httpx2. The experimental extra is not included in
datamodel-code-generator[all]. See
HTTP backend selection
for automatic and explicit selection behavior.
With GraphQL support:
pip install 'datamodel-code-generator[graphql]'
With Protocol Buffers support:
pip install 'datamodel-code-generator[protobuf]'
Docker:
docker pull koxudaxi/datamodel-code-generator
Published Docker images run as a non-root appuser. When writing generated files
to a bind-mounted directory, make sure the directory is writable by the container
user or pass an explicit Docker user, for example --user "$(id -u):$(id -g)".
🏃 Quick Start
Command
datamodel-codegen \
--input schema.json \
--input-file-type jsonschema \
--output-model-type pydantic_v2.BaseModel \
--preset standard-py312-20260826 \
--output model.py
This quick start uses standard-py312-20260826 as the modern Python 3.12 baseline.
Preset names include the target Python version: py312 means Python 3.12.
See CLI Reference for all options. See Presets,
--preset, --input-file-type, and
--output-model-type for this command.
For more schema-aware output that preserves schema-authored names, reuses models, and embeds generated
documentation, use practical-py312-20260826.
Input (schema.json)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Pet",
"type": "object",
"required": ["name"],
"properties": {
"name": {
"type": "string",
"description": "The pet's name"
},
"species": {
"type": "string",
"enum": ["dog", "cat", "bird", "fish"],
"default": "dog"
},
"age": {
"type": "integer",
"minimum": 0,
"description": "Age in years"
},
"vaccinated": {
"type": "boolean",
"default": false
}
}
}
Output (model.py)
# generated by datamodel-codegen:
# filename: schema.json
from __future__ import annotations
from enum import StrEnum
from typing import Annotated
from pydantic import BaseModel, ConfigDict, Field
class Species(StrEnum):
dog = 'dog'
cat = 'cat'
bird = 'bird'
fish = 'fish'
class Pet(BaseModel):
model_config = ConfigDict(
populate_by_name=True,
)
name: Annotated[str, Field(description="The pet's name")]
species: Species = Species.dog
age: Annotated[int | None, Field(description='Age in years', ge=0)] = None
vaccinated: bool = False
⚡ Speed up generation
By default, generated Python is currently formatted with black and isort. For faster generation without external
formatter dependencies, add --formatters builtin for standard generated model modules. In a future version, the
Black/isort dependencies will become opt-in and the default formatter will change to builtin.
If you prefer Ruff, install it with pip install 'datamodel-code-generator[ruff]' and use
--formatters ruff-check ruff-format for a fast external formatter.
Custom templates can emit Python outside the standard generated model patterns covered by builtin, so
custom-template output is not exhaustively validated. If --formatters builtin produces invalid or poorly formatted
output with a custom template, please open an issue with a small reproducer. See
Formatter Behavior for details.
See Performance Benchmarks for release benchmark data and interactive charts.
📖 Documentation
👉 Read the full documentation →
- 🧰 Presets - Recommended option bundles for modern output
- 🚀 Getting Started - Installation and first model
- 🖥️ CLI Reference - All command-line options
- 🧪 Playground - Try generation in your browser
- ⚙️ pyproject.toml - Configuration file
- 🔄 CI/CD Integration - GitHub Actions, pre-commit hooks
- ✅ Conformance Dashboard - External corpus coverage signals
- 📈 Performance Benchmarks - Release benchmark tables and interactive charts
- 🧭 Architecture - Generation pipeline and synchronized component inventory
- 🚀 One-liner Usage - uvx, pipx, clipboard integration
- ❓ FAQ - Common questions
📥 Supported Input
- OpenAPI 3 (YAML/JSON)
- AsyncAPI (YAML/JSON)
- JSON Schema
- MCP tool schemas
- XML Schema (XSD)
- Protocol Buffers / gRPC (
.proto) - Apache Avro schema (AVSC)
- JSON data
- YAML data
- Python dictionary
- CSV data
- GraphQL schema
- Python types (Pydantic, dataclass, TypedDict) via
--input-model
📤 Supported Output
- pydantic v2 BaseModel
- pydantic v2 dataclass
- dataclasses
- TypedDict
- msgspec Struct
✅ Conformance Signals
CI exercises datamodel-code-generator against pinned external corpora for XML Schema, JSON Schema, AsyncAPI, Apache Avro, and Protocol Buffers. See the Conformance Dashboard for the generated summary of runner scripts, tox environments, CI jobs, expected corpus counts, and upstream sources.
🍳 Common Recipes
CLI option quick starts
Use these starting points when combining options; each option links to the generated CLI reference for details and examples.
- Generate a local schema file: Pin the input type and destination when the source extension is ambiguous or generated output needs a stable path. Options:
--input,--input-file-type,--output. - Target Pydantic v2 on modern Python: Set the output model family and Python/Pydantic compatibility targets together. Options:
--output-model-type,--target-python-version,--target-pydantic-version. - Use modern Python annotations: Target a recent Python version and prefer built-in collection and union syntax in generated types. Options:
--target-python-version,--use-union-operator,--use-standard-collections. - Normalize incoming field names: Convert source names to Python identifiers while preserving explicit alias data for runtime IO. Options:
--snake-case-field,--original-field-name-delimiter,--aliases. - Generate operation-focused models: Limit OpenAPI output to operation shapes and name models from operation IDs and status codes. Options:
--openapi-scopes,--use-operation-id-as-name,--use-status-code-in-response-name. - Resolve remote references deliberately: Enable remote
$refloading and configure request metadata, timeouts, or local ref roots. Options:--allow-remote-refs,--http-headers,--http-timeout,--http-local-ref-path.
See the CLI Reference for the full option list and category-specific recipes.
🤖 Get CLI Help from LLMs
Generate a prompt to ask LLMs about CLI options:
datamodel-codegen --generate-prompt "Best options for Pydantic v2?" | claude -p
See LLM Integration for more examples.
🌐 Generate from URL
pip install 'datamodel-code-generator[http]'
datamodel-codegen --url https://example.com/api/openapi.yaml --output model.py
The http extra is the stable, non-deprecated backend. For the experimental
HTTPX2 alternative, pass --http-backend httpx2; see
HTTP backend selection.
⚙️ Use with pyproject.toml
[tool.datamodel-codegen]
input = "schema.yaml"
output = "src/models.py"
output-model-type = "pydantic_v2.BaseModel"
Then simply run:
datamodel-codegen
See pyproject.toml Configuration for more options.
🔄 CI/CD Integration
Validate generated models in your CI pipeline:
# Replace vX.Y.Z with a released action version.
- uses: koxudaxi/datamodel-code-generator@vX.Y.Z
with:
input: schemas/api.yaml
output: src/models/api.py
See CI/CD Integration for more options.
Coding agent skill
This repository includes an experimental Agent Skill that teaches compatible coding agents to run datamodel-codegen when generating Python models from OpenAPI, AsyncAPI, JSON Schema, GraphQL, JSON/YAML/CSV sample data, MCP tool schemas, Protocol Buffers, XML Schema, Apache Avro, or existing Python model objects.
See Coding Agent Skill for detailed guidance and troubleshooting.
Install the bundled skill directly from the CLI:
# Codex, project-local
datamodel-codegen --install-skill codex
# Claude Code, project-local
datamodel-codegen --install-skill claude-code
For a personal install, add --skill-scope user. Existing skills are preserved
unless you explicitly add --overwrite-skill.
Check your agent's current documentation for exact search paths.
💖 Sponsors
OpenAI |
🏢 Projects that use datamodel-code-generator
These public examples are grouped by how each project uses datamodel-code-generator.
Code generation and runtime integration
- openai/codex - Generate public Python SDK types from protocol schemas
- modelcontextprotocol/python-sdk - Generate MCP protocol models from vendored JSON Schemas
- modular/modular - Generate MAX Serve KServe schemas from OpenAPI with datamodel-codegen
- apache/airflow - Generate OpenAPI datamodels for airflow-ctl and task-sdk via pyproject codegen config
- PostHog/posthog - Generate Pydantic models from JSON Schema
- airbytehq/airbyte - Generate Python, Java/Kotlin, and Typescript protocol models
- open-metadata/OpenMetadata - datamodel_generation.py
- topoteretes/cognee - Runtime generation of graph data models from JSON Schema
- e2b-dev/E2B - Generate MCP server TypedDict models via Makefile
- DataDog/integrations-core - Config models
- open-telemetry/opentelemetry-python - Generate SDK configuration dataclasses from JSON Schema
Development, testing, and evaluation
- browser-use/browser-use - Evaluation dependency
- vllm-project/vllm - Test dependency for MiniCPM3 tests
- stanfordnlp/dspy - Generate Pydantic models from JSON Schema for reliability tests
🔗 Related Projects
- fastapi-code-generator - Generate FastAPI app from OpenAPI
- pydantic-pycharm-plugin - PyCharm plugin for Pydantic
🤝 Contributing
See Development & Contributing for how to get started!
👥 Maintainers
- Koudai Aono (@koxudaxi) - Lead maintainer
- Bernát Gábor (@gaborbernat) - Maintainer
- Antonio Spadaro (@ilovelinux) - Maintainer
📄 License
MIT License - see LICENSE for details.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file datamodel_code_generator-0.76.1.tar.gz.
File metadata
- Download URL: datamodel_code_generator-0.76.1.tar.gz
- Upload date:
- Size: 2.2 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6f9e94caa5c82be0e0c6f2cf87024920aef0a979897b668734a99d25db289b20
|
|
| MD5 |
e46c478e8560868ce78e73f8acc143af
|
|
| BLAKE2b-256 |
4b94fad95512b15f4fea6c39ba1205a237049c9a0d7fe3211e34c235cd150679
|
Provenance
The following attestation bundles were made for datamodel_code_generator-0.76.1.tar.gz:
Publisher:
publish.yaml on koxudaxi/datamodel-code-generator
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
datamodel_code_generator-0.76.1.tar.gz -
Subject digest:
6f9e94caa5c82be0e0c6f2cf87024920aef0a979897b668734a99d25db289b20 - Sigstore transparency entry: 2684385064
- Sigstore integration time:
-
Permalink:
koxudaxi/datamodel-code-generator@2c28016935cb8784e87f9c622fdc5bd7f6612411 -
Branch / Tag:
refs/tags/0.76.1 - Owner: https://github.com/koxudaxi
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yaml@2c28016935cb8784e87f9c622fdc5bd7f6612411 -
Trigger Event:
push
-
Statement type:
File details
Details for the file datamodel_code_generator-0.76.1-py3-none-any.whl.
File metadata
- Download URL: datamodel_code_generator-0.76.1-py3-none-any.whl
- Upload date:
- Size: 653.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9670c48ac432762f8e14641d769c37a9e1558e35dd0400727fcc1def47f6f374
|
|
| MD5 |
700a39cc8228b7cef40aa90f2fcaebfe
|
|
| BLAKE2b-256 |
1914c1c4d7e96cf7e06c6036e0967a33866fd6e97649fab1788dac415d378a89
|
Provenance
The following attestation bundles were made for datamodel_code_generator-0.76.1-py3-none-any.whl:
Publisher:
publish.yaml on koxudaxi/datamodel-code-generator
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
datamodel_code_generator-0.76.1-py3-none-any.whl -
Subject digest:
9670c48ac432762f8e14641d769c37a9e1558e35dd0400727fcc1def47f6f374 - Sigstore transparency entry: 2684385093
- Sigstore integration time:
-
Permalink:
koxudaxi/datamodel-code-generator@2c28016935cb8784e87f9c622fdc5bd7f6612411 -
Branch / Tag:
refs/tags/0.76.1 - Owner: https://github.com/koxudaxi
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yaml@2c28016935cb8784e87f9c622fdc5bd7f6612411 -
Trigger Event:
push
-
Statement type:
