<!-- related-cli-options: --formatters -->

# 🖌️ Code Formatting

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

!!! warning "Experimental"
    The built-in formatter (`--formatters builtin`) is experimental and may change as generated-output coverage is
    expanded.

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

## 🎯 Default Behavior

!!! warning "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.

```bash
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.

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

See [Formatter Behavior](formatter-behavior.md) 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](https://github.com/astral-sh/ruff) is a fast Python linter and formatter. To use it:

!!! note "Installation Required"
    ruff is an optional dependency. Install it with:
    ```bash
    pip install 'datamodel-code-generator[ruff]'
    ```

```bash
# 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`:

```toml title="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

```toml title="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:

```bash
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](custom-formatters.md) for details.

---

## 📖 See Also

- 🖌️ [Formatter Behavior](formatter-behavior.md) - Built-in formatter scope and configuration precedence
- 🖥️ [CLI Reference: `--formatters`](cli-reference/template-customization.md#formatters) - Specify code formatters
- 💬 [CLI Reference: `--use-double-quotes`](cli-reference/template-customization.md#use-double-quotes) - Force double quotes
- 🎨 [Custom Formatters](custom-formatters.md) - Create your own formatters
- ⚙️ [pyproject.toml Configuration](pyproject_toml.md) - Configure datamodel-codegen options
