Migrate to Ruff as the default formatter for improved performance

[koxudaxi]

Summary

Propose migrating from Black to Ruff as the default formatter for significantly improved performance.

Motivation

Performance Benchmarks

Tested with a 2000-definition schema (3 runs average):

Formatter	Format Time	Improvement
Black + isort	2.355s	(baseline)
Ruff format + isort	0.487s	79% faster
Ruff format only	0.243s	90% faster

Total processing time improvement: 29-33%

For large schemas (like Kubernetes CRDs with 10,000+ definitions), formatting can be a major bottleneck. This change would significantly improve the user experience for large-scale code generation.

Adoption Statistics (December 2025)

Package	Monthly Downloads	GitHub Stars
ruff	111M	44.7k
black	90M	41.2k

Ruff has surpassed Black in downloads and is now used by major projects including:

• Pydantic (our primary output format)
• FastAPI, Pandas, PyTorch, Hugging Face, Apache Airflow, and 118,000+ other projects

Compatibility

Ruff formatter achieves >99.9% compatibility with Black (source).

Proposal

Phase 1: Documentation + Deprecation Warning

1. Update documentation to recommend Ruff as the preferred formatter

   • Add migration guide
   • Document performance benefits

2. Add DeprecationWarning when Black formatter is used

   warnings.warn(
       "Black formatter is deprecated and will be removed in a future version. "
       "Consider using --formatters ruff-format for better performance.",
       DeprecationWarning,
   )

Phase 2: Change Default (Future Major Release)

1. Change DEFAULT_FORMATTERS from [black, isort] to [ruff-format]
2. Users can still use --formatters black,isort for the original behavior

Considerations

• Add ruff as a required dependency (currently optional)
• Determine timeline for Phase 2

Related

• Addresses performance concerns from _get_unique_name take really long with large swagger definition file #2286

---

Feedback welcome via comments or reactions.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[github-actions]

📢 Related PR Released: 0.52.0

PR #2895, which references this issue, has been released. See the release notes for details.

Note: This issue was not explicitly closed by the PR.

[ilovelinux]

#3058 discuss about allowing to not install any formatter because they are useless in some use-cases (as the one described in the issue). Despite they can be disabled, they are still marked as required dependencies.

It made me think that I'm not sure I would consider formatting the generated code as a core part of the project.

I think setting a default formatter could be avoided, and instead:

• Auto-detect the available ones, if --formatters has't been set, maybe with a warning.
• Allow users to opt-in to formatters as optional dependencies.

This would improve decoupling of the project from the formatters' projects and avoid dependency hell. 🙂

@koxudaxi WDYT?