Skip to content

🖌️ Code Formatting

Generated code is automatically formatted using code formatters. By default, black and isort are used to produce consistent, well-formatted output.

🎯 Default Behavior

Future Change

In a future version, the default formatter will change to builtin, and the external formatter dependencies (black and isort) will become opt-in. To prepare for dependency-free formatting, try the built-in formatter with --formatters builtin.

CLI users: To suppress this warning, use --disable-warnings or explicitly specify --formatters black isort.

Library users: Explicitly pass formatters=[Formatter.BLACK, Formatter.ISORT] to suppress this warning.

datamodel-codegen \
    --input schema.yaml \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

This runs the following formatters in order:

  1. isort - Sorts and organizes imports
  2. black - Formats code style

🛠️ Available Formatters

Formatter Description
builtin Dependency-free formatter for generated code
black Code formatting (PEP 8 style)
isort Import sorting
ruff-check Linting with auto-fix
ruff-format Fast code formatting (black alternative)

⚡ Speed up generation

The default formatter list is currently black and isort. For standard generated model modules, --formatters builtin is the recommended dependency-free choice. 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.

Using the built-in formatter

The built-in formatter is designed for code generated by this project. It does not require external formatter dependencies. It formats the leading import block and applies basic whitespace cleanup. It is not a full replacement for Black, isort, or Ruff on arbitrary Python code. It is used as an alternative to external formatters. If builtin is passed together with black, isort, ruff-check, or ruff-format, the built-in formatter is ignored.

datamodel-codegen \
    --formatters builtin \
    --input schema.yaml \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

See Formatter Behavior for the exact built-in formatter scope and configuration precedence.

If you use --custom-template-dir, review the built-in formatter scope before selecting builtin. Custom templates can generate Python outside the supported model patterns, so custom-template output is not exhaustively validated with the built-in formatter. If --formatters builtin produces invalid or poorly formatted output with a custom template, please open an issue with a small reproducer.

⚡ Using ruff instead of black

Ruff is a fast Python linter and formatter. To use it:

Installation Required

ruff is an optional dependency. Install it with: 

pip install 'datamodel-code-generator[ruff]'


# Use ruff for both linting and formatting
datamodel-codegen \
    --formatters ruff-check ruff-format \
    --input schema.yaml \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

# Use ruff-format as a black replacement
datamodel-codegen \
    --formatters isort ruff-format \
    --input schema.yaml \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

🚫 Disable formatting

datamodel-codegen requires at least one formatter when using the CLI --formatters option.

To disable built-in formatting entirely, configure it via pyproject.toml:

pyproject.toml
[tool.datamodel-codegen]
formatters = []

⚙️ Configuration via pyproject.toml

Formatters read their configuration from pyproject.toml. The effective search path starts from the output path directory, or the current working directory when no output path is available, and then checks parent directories.

The built-in formatter uses line length for import wrapping and generated model statement wrapping. Its precedence is:

  1. API builtin_format_line_length
  2. [tool.datamodel-codegen].builtin-format-line-length
  3. [tool.ruff].line-length
  4. [tool.black].line-length
  5. [tool.isort].line_length
  6. 88

📝 Example Configuration

pyproject.toml
[tool.datamodel-codegen]
formatters = ["builtin"]
builtin-format-line-length = 100

[tool.black]
line-length = 100
skip-string-normalization = true

[tool.isort]
profile = "black"
line_length = 100

[tool.ruff]
line-length = 100

[tool.ruff.format]
quote-style = "single"

💬 String Quotes

By default, string quote style is determined by your formatter configuration. To force double quotes regardless of configuration:

datamodel-codegen \
    --use-double-quotes \
    --input schema.yaml \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

This overrides skip_string_normalization in black config. When using --formatters builtin without --use-double-quotes, the built-in formatter also reads [tool.black].skip-string-normalization. Set it to false to normalize simple generated string literals to double quotes.

🎨 Custom Formatters

You can create custom formatters for specialized formatting needs. See Custom Formatters for details.

📖 See Also