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-20260909 \
--output model.py
This quick start uses standard-py312-20260909 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-20260909.
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
Choose a formatter
Choose a formatter to match your project and generation priorities:
- Projects using Ruff: use
--formatters ruff-check ruff-formatto keep generated code consistent with the project's formatting and lint policy. Install it withpip install 'datamodel-code-generator[ruff]'. - No Ruff, Black, or isort, or generation speed is the priority: use
--formatters builtinto avoid running external formatters on standard generated model modules. - Projects using Black/isort: keep
--formatters black isortto preserve the project's formatting and existing generated output.
The current default remains Black/isort, which are still required dependencies. Omitting formatter options continues
normal generation. The future builtin default is intended to reduce required installation dependencies and version
constraints; Ruff will still be recommended for projects that use Ruff. Formatters are never selected automatically
based on installed packages or Ruff configuration. The new [black] and [isort] extras prepare for later
optional installation; their ranges and environment markers match the current required dependencies.
Selecting only a formatter preserves your other generation settings; a preset also supplies model-generation options.
Explicit formatter selection does not pin formatter versions or guarantee byte-for-byte output stability.
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: datamodel-code-generator/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
Release files for datamodel-code-generator 0.81.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| datamodel_code_generator-0.81.0.tar.gz | 2.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| datamodel_code_generator-0.81.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.6 MB
Release files / datamodel_code_generator-0.81.0.tar.gz
| Download URL | datamodel_code_generator-0.81.0.tar.gz |
|---|---|
| Size | 2.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3b4d1639cc7430f7e34fddc3827fb5d3eb0a4f5394750890c46ba2a9d56e3ee2
|
|
BLAKE2b-256 checksum How to use checksums |
41a187deb406ca27b0ae25cda946940208dfe2a2953b7fef20f8a968746e6b36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / datamodel_code_generator-0.81.0-py3-none-any.whl
| Download URL | datamodel_code_generator-0.81.0-py3-none-any.whl |
|---|---|
| Size | 721.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82ff0c295685065a83c530ce42ec03fc75b7ca01e72083eb8232d68f7637013a
|
|
BLAKE2b-256 checksum How to use checksums |
8430acea9e8d4c5e7819c10b25581accfa805e5368ec564fc210c8f4c4ffd666
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
