# format! - build a String

> Use Rust format! when you need an owned String produced with the standard formatting syntax.

HTML: https://rustprint.com/output/format-macro/

`format!` runs Rust's standard formatting machinery and returns a new owned `String`. Use it when the formatted text needs to be stored, returned, compared, or passed to an API that requires a string value.

**Building an owned String with format!**

```rust
let name = "Rust";
let message = format!("Hello, {name}!");
assert_eq!(message, "Hello, Rust!");
```

## Same syntax, different destination

The fields inside `format!` are the same fields used by `println!`, `write!`, and the rest of the formatting family. Argument capture, width, precision, signs, numeric bases, and formatting traits all behave through the same `std::fmt` rules.

What changes is the result: `format!` gives you the finished `String` instead of writing to stdout or an existing destination.

## When format! is the right tool

Use it when ownership of the text is useful:

- build a message to return from a function
- create a key or label
- construct a value required by an API that accepts `String`
- keep the result for later use

If the next operation is immediately writing these formatted bytes into an existing destination, `write!` can avoid the intermediate `String`.

## Runtime format strings are not supported

The format string is compiler-checked and must be a string literal. You cannot pass an arbitrary runtime string and ask `format!` to interpret replacement fields inside it.

That restriction lets Rust validate formatting syntax and argument compatibility at compile time. See [dynamic format strings in Rust](/format/runtime-format-strings/index.md) for a CI-asserted compile-fail example and the distinction between a runtime template and runtime values.

## format! vs to_string()

For one value with its normal `Display` representation, `.to_string()` is often simpler. `format!` becomes useful when literal text, multiple arguments, or a non-default format specification is part of the result.

If you need to pass formatting arguments through an API without first allocating the final `String`, see [format_args!](/output/format-args/index.md).

## Sources

- [format!](https://doc.rust-lang.org/std/macro.format.html)
- [std::fmt](https://doc.rust-lang.org/std/fmt/)

## Related RustPrint guides

- [Dynamic format strings in Rust: why format! requires a literal](/format/runtime-format-strings/index.md): Understand why Rust format! cannot use a runtime String as its format template, while runtime values still work normally.
- [Rust format strings - syntax, width, precision, and traits](/format/format-strings/index.md): Read Rust format strings from {} through argument capture, width, precision, alignment, escaping, and formatting traits.
- [format_args! - deferred formatting arguments](/output/format-args/index.md): Use Rust format_args! to create fmt::Arguments for forwarding formatted values without first allocating a String.
- [Rust write! and writeln! - format into strings, files, and buffers](/output/write-and-writeln/index.md): Use Rust write! and writeln! to format directly into String buffers, byte writers, files, sockets, and other write_fmt destinations.