🖌️ Code Formatting¶

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

This page is a practical guide for choosing and configuring formatters. For the exact built-in formatter scope and configuration precedence, see Formatter Behavior.

🎯 Default Behavior¶

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¶

Choose a formatter¶

Choose a formatter to match your project and generation priorities:

• Projects using Ruff: use --formatters ruff-check ruff-format to keep generated code consistent with the project's formatting and lint policy. Install it with pip install 'datamodel-code-generator[ruff]'.
• No Ruff, Black, or isort, or generation speed is the priority: use --formatters builtin to avoid running external formatters on standard generated model modules.
• Projects using Black/isort: keep --formatters black isort to 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.

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:

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:

[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 or [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¶

[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¶

• 🖌️ Formatter Behavior - Built-in formatter scope and configuration precedence
• 🖥️ CLI Reference: --formatters - Specify code formatters
• 💬 CLI Reference: --use-double-quotes - Force double quotes
• 🎨 Custom Formatters - Create your own formatters
• ⚙️ pyproject.toml Configuration - Configure datamodel-codegen options

Dependency migration¶

See Dependency migration notices for Black/isort extras, separate optional-installation and old-version warnings, unchanged current requirements, and the distinction between DCG runtime Pydantic and generated-code compatibility. Old presets without formatters retain the implicit-default warning.