# uv format: Code Formatting Comes to uv (experimentally!)

The latest [uv](https://pydevtools.com/handbook/reference/uv.md) release ([0.8.13](https://github.com/astral-sh/uv/blob/main/CHANGELOG.md#0813)) quietly introduced an experimental new command that Python developers have been waiting for: `uv format`. This addition brings code formatting directly into uv's toolkit, eliminating the need to juggle multiple tools for basic Python development workflows.

## What is uv format?

The `uv format` command provides Python code formatting through uv's interface. Under the hood, it calls [Ruff](https://pydevtools.com/handbook/reference/ruff.md)'s formatter to automatically style your code according to consistent standards.

> [!NOTE]
> Charlie Marsh, creator of uv, adds [this explanation on Hacker News](https://news.ycombinator.com/item?id=44978500):
> > To clarify, `ruff` and `uv` aren't being merged. They remain separate tools. This is more about providing a simpler experience for users that don't want to think about their formatter as a separate tool.
> >
> > The analogy would be to Cargo: `cargo fmt` just runs `rustfmt`, but you can also run `rustfmt` separately if you want.

## Getting Started

First, make sure you're running uv 0.8.13 or later. If you need to upgrade, check out our guide on [upgrading uv](https://pydevtools.com/handbook/how-to/how-to-upgrade-uv.md).

Once upgraded, formatting your project is straightforward:

```bash
# Format all Python files in your project
uv format

# Check formatting without making changes
uv format --check

# See what would change without applying it
uv format --diff
```

The command works just like running `ruff format` in your project root, but through uv's interface.

## Passing Arguments to Ruff

You can pass additional arguments to Ruff by placing them after `--`:

```bash
# Set a specific line length
uv format -- --line-length 100

# Format only specific files
uv format -- src/mymodule/core.py

# Use multiple Ruff options
uv format -- --line-length 88 --preview
```

This flexibility means you can customize formatting behavior without losing uv's conveniences.


> [!WARNING]
> Since this is an experimental feature, expect some rough edges:
>
> - The command may change in future releases
> - Integration with uv's project model might evolve
> - Error handling and output formatting could improve


Try out `uv format` in your next project and see how it fits into your development workflow. The experimental nature means your feedback could help shape how this feature evolves.

## Learn more

- [Set up Ruff for formatting and checking your code](https://pydevtools.com/handbook/tutorial/set-up-ruff-for-formatting-and-checking-your-code.md) (Tutorial)
- [How to configure recommended Ruff defaults](https://pydevtools.com/handbook/how-to/how-to-configure-recommended-ruff-defaults.md)
- [How to migrate from Black to the Ruff formatter](https://pydevtools.com/handbook/how-to/how-to-migrate-from-black-to-ruff-formatter.md)
- [Ruff reference](https://pydevtools.com/handbook/reference/ruff.md)
- [uv reference](https://pydevtools.com/handbook/reference/uv.md)