std::fmt

format! and println! macros, plus Display and Debug formatting with {}, {:?}, and {:#?}.

std::fmt is the standard-library module behind Rust formatting. The macros you usually call — format!, println!, print!, eprintln!, and write! — live in the prelude and expand to this module. They are macros, not functions, and they are not a third-party logging crate.

This page documents the format string, the difference between Display and Debug, and how to implement Display. It does not cover every format trait or every alignment specifier.

Examples were compiled with rustc 1.90.0 using --edition=2024 and run as a plain binary. See the Rust 1.90.0 documentation for the complete API.

Rust reference overview →

API index

APISummary
format!, println!, print!Build a String or write formatted text to standard output. These are standard-library macros, not functions, and not methods on str.
Display, Debug, and FormatterChoose {} for Display and {:?} or {:#?} for Debug. Implementing Display is how a type gets a stable, readable format for format! and println!.

format! and println!

format! returns an owned String. println! writes to standard output and appends a newline. print! writes to standard output without adding a newline. In edition 2021 and later, a format string can capture a named value with {port} instead of repeating the argument.

The signatures below are simplified. The complete macro rules are in the official documentation linked from each entry.

format!, println!, print!

format!(format_string, ...) -> String
println!(format_string, ...)
print!(format_string, ...)

Build a String or write formatted text to standard output. These are standard-library macros, not functions, and not methods on str.

ParameterDescription
format_stringA string literal with placeholders such as {}, {name}, {:?}, or {:#?}. Ordinary braces that should appear in the output are written as {{ and }}.
...Values to format. Positional arguments follow the string. Named values already in scope can be captured as {name} in edition 2021 and later.

Returns: format! returns a String. println! and print! return () after writing to standard output.

  • A trailing newline comes from println!, not from format!. format!("port {port}") does not add a newline of its own.
  • These macros format through the Display or Debug traits. They do not serialize data as JSON; that is not part of std.
rust
fn main() {
    let port = 80;
    let text = format!("listen on {port}");
    println!("{text}");
    print!("port={port}");
    println!(" ready");
}

Expected output

listen on 80
port=80 ready

Related: format! macro, println! macro

Official documentation →

Display and Debug

{} uses the Display trait, which is meant for user-facing text. {:?} uses Debug, which is meant for programmers, and {:#?} is the pretty-printed Debug form. Many standard-library types implement both. For a type you define, #[derive(Debug)] is usually enough for {:?}; Display must be implemented by hand when you want {} to work.

Display, Debug, and Formatter

trait Display {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}
trait Debug {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result;
}

Choose {} for Display and {:?} or {:#?} for Debug. Implementing Display is how a type gets a stable, readable format for format! and println!.

ParameterDescription
fThe Formatter that write! and the format macros write into. Returning Err from fmt propagates a formatting failure, which is rare for in-memory format! but matters for writers.

Returns: fmt returns std::fmt::Result, an alias for Result<(), std::fmt::Error>.

Errors and panics

  • std::fmt::Error — Signals that the underlying writer failed or that formatting could not be completed. format! into a String does not normally produce this error.
  • The Debug output of a struct includes the type and field names. That form is for debugging; do not treat it as a stable interchange format.
  • {:#?} inserts newlines and indentation. The exact whitespace is part of the current Debug implementation and is checked here against rustc 1.90.0.
  • write!(f, "port {}", self.value) inside Display uses Display for the inner value, not Debug.
rust
use std::fmt::{self, Display, Formatter};

#[derive(Debug)]
struct Port {
    value: u16,
}

impl Display for Port {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "port {}", self.value)
    }
}

fn main() {
    let port = Port { value: 80 };
    println!("{port}");
    println!("{port:?}");
    println!("{port:#?}");
    println!("{}", format!("listen on {port}"));
}

Expected output

port 80
Port { value: 80 }
Port {
    value: 80,
}
listen on port 80

Related: Display, Debug

Official documentation →